writing-great-skills

When to Use

Use when this workflow matches the user request: Reference for writing and editing skills well — the vocabulary and principles that make a skill predictable.

_Source: mattpocock/skills (MIT)._A skill exists to wrangle determinism out of a stochastic system. Predictability — the agent taking the same process every run, not producing the same output — is the root virtue; every lever below serves it.

Bold terms are defined in GLOSSARY.md; look them up there for the full meaning.

Invocation

Two choices, trading different costs:

• A model-invoked skill keeps a description, so the agent can fire it autonomously and other skills can reach it (you can still type its name too). It contributes to context load — the description sits in the window every turn. Mechanics: omit disable-model-invocation, and write a model-facing description with rich trigger phrasing ("Use when the user wants…, mentions…").
• A user-invoked skill strips the description from the agent's reach: only you, typing its name, can invoke it — and no other skill can. Zero context load, but it spends cognitive load: you are the index that must remember it exists. Mechanics: set disable-model-invocation: true; the description becomes human-facing — a one-line summary, trigger lists stripped.

Pick model-invocation only when the agent must reach the skill on its own, or another skill must. If it only ever fires by hand, make it user-invoked and pay no context load.

When user-invoked skills multiply past what you can remember, that piled-up cognitive load is cured by a router skill: one user-invoked skill that names the others and when to reach for each.

Writing the description

A model-invoked description does two jobs — state what the skill is, and list the branches that should trigger it. Every word increases context load, so a description earns even harder pruning than the body:

• Front-load the skill's leading word — the description is where it does its invocation work.
• One trigger per branch. Synonyms that rename a single branch are duplication — "build features using TDD … asks for test-first development" is one branch written twice. Collapse them; keep only genuinely distinct branches.
• Cut identity that's already in the body. Keep the description to triggers, plus any "when another skill needs…" reach clause.

Information hierarchy

A skill is built from two content types — steps and reference — that mix freely: a skill can be all steps, all reference, or both. The core decision is which to use and where each sits on the information hierarchy, a ladder ranked by how immediately the agent needs the material:

1. In-skill step — an ordered action in SKILL.md, the primary tier: what the agent does, in order. Each step ends on a completion criterion, the condition that tells the agent the work is done. Make it checkable (can the agent tell done from not-done?) and, where it matters, exhaustive ("every modified model accounted for", not "produce a change list") — a vague criterion invites premature completion.
2. In-skill reference — a definition, rule, or fact in SKILL.md, consulted on demand. Often a legitimately flat peer-set (every rule of a review on one rung) — a fine arrangement, not a smell. This skill is all reference.
3. External reference — reference pushed out of SKILL.md into a separate file, reached by a context pointer, loaded only when the pointer fires. (Spans disclosed reference — a sibling file like GLOSSARY.md, still part of the skill — through fully external reference that lives outside the skill system and any skill can point at.)

A demanding completion criterion drives thorough legwork — the digging the agent does within the work — whether the skill has steps or not, since "every rule applied" binds flat reference just as "every step done" binds a sequence.

Push too little down and the top bloats; push too much and you hide material the agent actually needs. That tension is the whole decision.

…