---
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 <thing> -> <skill-name>.` The target must resolve to
   a real skill directory or agent file in the authoring source. `validate.sh` checks that
   deterministically and grades it by notation: an unresolved `/name` or arrow target is an ERROR
   and reaches the report as a Structure FAIL, while an unresolved prose-form target ("use `y`
   instead") is only a SUGGESTION unless a second target in the same sentence resolves. Take the
   script's tier as given and report it once, under Structure.

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.)

The FAIL and SUGGESTION criteria for this dimension live in `references/finding-criteria.md`,
which Step 3 loads on every run.