--- source_keys: - agentskills-spec - agentskills-optimizing-descriptions --- # Description Quality Reference Upstream source: agentskills.io — optimizing-descriptions, specification. House contract: ADR-0020, the context budget. The house contract is narrower than the spec rather than a reinterpretation of it: where both speak, both must be satisfied. ## Why the description is the expensive part At startup an agent loads only the `name` and `description` of every installed skill. The body is never seen until the skill triggers. The description therefore carries the entire triggering burden **and** is paid for in every session, whether the skill fires or not. A second cost is less obvious and is a correctness hazard rather than a token cost: a description that summarises the workflow is a shortcut the agent takes *instead of* reading the body. A measured failure upstream — a description saying "code review between tasks" — produced one review where the body's flowchart specified two. ## Step 0 — establish which contract applies Read the frontmatter before judging a single word. - **`disable-model-invocation: true`** — the skill is hand-invoked. Its description is never matched against user intent, so it is not a routing string. It carries **one plain human-facing sentence** stating what the skill does. Audit it for that and nothing else. Reporting a missing trigger clause, a missing boundary clause or absent indirect triggers on a hand-invoked skill is a wrong finding, not a strict one. - **No such flag** — the skill is model-invoked and the rest of this file applies. ## The three-part shape A model-invoked description carries exactly three things: 1. **Trigger clause.** When to invoke, phrased imperatively: `Use when ...`. Not `This skill ...` — the agent is deciding whether to act, not reading a catalogue entry. 2. **At most one capability clause.** What it does, in one clause. Never an enumeration. 3. **Boundary clause.** Compressed form: `Not -> .` The target must resolve to a real skill directory or agent file in the authoring source; `validate.sh` checks that deterministically and a dangling target already surfaces as a Structure FAIL. Everything else belongs in the body or in `README.md`. ## Indirect triggers — conditional, never blanket Add "even if the user doesn't say X" **only where the user's natural phrasing genuinely omits the domain word.** True for the `gitea-*` family: people say "create an issue", not "create a Gitea issue". False for `git-commits`: nobody asks for a commit without saying commit. A blanket indirect-trigger clause on a skill whose domain word is unavoidable is padding charged to every session. ## Near-miss exclusions Add a boundary clause only where a sibling skill could plausibly steal the activation. Use strong near-misses — queries that share keywords but need something different — not weak ones ("write a fibonacci function"). One boundary clause per genuine near-miss; a list of four is enumeration wearing a boundary's clothes. ## Before / after ```yaml # FAIL — enumeration first, mechanics as the opener, a blanket indirect trigger, # and 300+ characters of it preloaded into every session forever. description: > Analyze CSV and tabular data files — compute summary statistics, add derived columns, generate charts, and clean messy data. Use when the user has a CSV, TSV, or Excel file and wants to explore, transform, or visualize the data, even if they don't explicitly mention "CSV" or "analysis." # PASS — trigger, one capability clause, boundary. The four verbs the FAIL # version enumerates are the body's job; the router cannot act on them. description: > Use when the user has a CSV, TSV, or Excel file and wants it explored, transformed, or charted. Not schema design -> data-model. ``` (`data-model` is illustrative. In a real description the target has to resolve.) ## Auditing guidance Flag as FAIL if: - **Over 400 characters.** Measured on the folded YAML value, not the raw source lines. `validate.sh` reports the number; do not re-derive it, but do point the Fix at what to cut. - **Internal mechanics appear in the description.** Any of: - capability enumeration or a feature list; - output-format detail ("Produces a compact findings report with Why and Fix per finding"); - composition or architecture notes ("composes X rather than duplicating Y", "a cross-cutting shared skill", "the human-facing entry point", "replaces the old flat invocation"); - implementation detail ("self-validates via a bundled deterministic script"). None of it can change a routing decision and all of it is preloaded. `Kyberforge.CompositionNote` catches the common phrasings deterministically; the rest is judgment. This is the rule that deflates a description, so apply it before reaching for length. - **The same trigger stated twice in two registers** — a verb list, then the same verbs re-quoted as user phrasings, usually in the same order. One register, whichever routes better. - **Descriptive rather than imperative phrasing** (`This skill ...`, `This is the ...`). `Kyberforge.DescriptionOpener` catches any opener matching `^This`. - **Vague capabilities** ("helps with APIs" where "parses and validates OpenAPI specs" was available). `Kyberforge.VagueWording` catches the known filler; imprecision outside that list is judgment. - **A boundary clause naming a target that does not resolve** to a real skill directory or agent file in the authoring source. `validate.sh` reports the unresolved name. - **Trigger-list, boundary or indirect-trigger content on a hand-invoked skill** — see Step 0. - **Over 1024 characters** — the agentskills.io specification ceiling, unchanged and independent of the 400-character house ceiling above. Flag as SUGGESTION if: - **Over 250 characters** but at or under 400. This tier is what moves the corpus average; the FAIL tier only stops outliers. Report it rather than treating a 399-character description as clean. - A near-miss exclusion is present but targets a weak near-miss. - An indirect trigger is present and warranted but could name the omitted phrasing more precisely.