Writing a skill

Read these first

• Progressive disclosure

What you will know

• Write a description that reliably routes the right tasks to the skill

  The description is doing retrieval: it decides whether the skill is ever considered.

• Show a vague description causing a skill never to fire

  A semantically correct label can still lose to competing skills or fall below a matching threshold, making the capability appear broken.

• Scope a skill narrowly rather than making it a manual

  Broad skills create ambiguous matches and conflicting instructions, while a tight boundary makes both selection and testing observable.

• Decide what belongs in the body and what belongs in a bundled file

  Always-loaded instructions consume context on every invocation; supporting material should be deferred when only some tasks need it.

• Rewrite descriptive prose as imperative steps and remove material that does not change the agent's action

  Background, examples, and duplicated guidance spend tokens and can introduce competing interpretations without improving execution.

Chapters

1. 1

   Retrieval runs on the description, not on the body

   'Helps with database work' and a 300-line body are both defects, but only one of them makes the skill's value zero. The description decides whether anything loads at all, so a bad one renders the body's cost irrelevant while a bloated body at least still works. Rank fixes by which failure removes the skill from consideration entirely, not by which one has more lines.

   Read chapter
2. 2

   Write the description in the words of someone with the problem

   `nomad-drain` described as 'procedure for draining a Nomad client node prior to decommissioning' is accurate and never fires, because engineers say 'take box i-0a4f out of the cluster'. The description competes for real requests written by people who do not yet know the procedure exists. Name the triggering situations and the neighbouring tasks it is not for, then check the phrasing against the request log.

   Read chapter
3. 3

   One skill covering five topics wins the wrong requests and loses the right ones

   A single `frontend` skill spanning component conventions, state management, test structure, accessibility and design tokens needs a description broad enough to match all five. That description cannot discriminate between them, so it takes requests that needed one narrow section and loses to more specific skills on the requests it should have taken. A tight boundary is what makes selection and testing observable at all.

   Read chapter
4. 4

   Cross-referencing two skills builds a routing table nobody can read

   When `pr-review` wins every request to review a PR that changes a public API, the compatibility rules in `api-compat` are simply never seen, and no rewording of either description fixes a genuine overlap. Adding 'also load api-compat when the diff touches an endpoint' makes behaviour depend on a pointer you cannot verify from the outcome. Weigh merging against re-cutting the boundary, and name what would reverse your choice.

   Read chapter
5. 5

   Cut anything that does not change the action, keep what pins a format

   'Our API guidelines were established in 2021 after several incidents' becomes 'use cursor pagination for any endpoint returning a collection'. Rationale and repeated examples spend context and invite competing readings; the `billing-v1` exception and the one example that pins an otherwise ambiguous format stay. A background fact that measurably changes the agent's plan is not an exception to the rule — it changes the action. What survives the cut is then sorted between body and bundled file by a different question: what fraction of the triggering tasks need it, and whether the agent can act at all without it.

   Read chapter
6. 6

   A hedge is a rule the model can honour and still break

   'Avoid combining type widening with backfills where possible' is item seven of nine, and reviewers keep finding violations. Two things are wrong: the hedge gives permission, and eight competitors dilute it. Rewriting raises compliance without reaching total, which is the expected residual of a probabilistic instruction rather than a bug to escalate. When two steps in a body contradict each other, the fix is a rewrite, not another item.

   Read chapter
7. 7

   A rule that must never break belongs in a gate, not a body

   Accepting the residual is not the whole answer, because some rules have no acceptable violation rate. Those move out of the instruction entirely and into something deterministic: tool-side validation that rejects the call, a CI or pre-commit check on the artefact, a schema that makes the bad state unrepresentable. The skill's job then shrinks to explaining the gate instead of substituting for it. This is also the test that thins a nine-item list — a rule you would not build a gate for is one whose occasional violation you have already agreed to live with.

   Read chapter