writing-great-skills

Skills exist to wring determinism out of a stochastic system.Predictability—the agent taking the same processevery time, rather than producing the same output—is the fundamental virtue; every lever below serves it.

Bold terms are defined in GLOSSARY.md ; look there when you need the full meaning.

Invocation

Two choices, with different costs:

Model-invoked skill keeps the description, so the agent can trigger it autonomously, and other skills can reach it too (the user can still type the name manually). It incurs context load: the description is in the context window every turn. Mechanism: omit disable-model-invocation, and write a model-facing description with rich trigger phrasing ("Use when the user wants…", "mentions…").
User-invoked skill removes the description from the agent's reach: it can only be invoked when the user types the name, and other skills cannot invoke it either. Zero context load, but it costs cognitive load：the user is the index that has to remember it exists. Mechanism: set disable-model-invocation: true；description to become a one-line summary that humans see, without a trigger list.

Choose model-invocation only when the agent must find the skill on its own, or another skill must invoke it. If it will only ever be triggered manually, make it user-invoked and don't pay the context load.

When user-invoked skills pile up beyond what the user can remember, the accumulated cognitive load is cured by a router skill : a user-invoked skill responsible for naming the other user-invoked skills and when to use them.

Writing the description

Model-invoked description does two things: states what the skill is, and lists the branchesthat should trigger it. Every word adds context load, so the description needs trimming even more than the body:

Put the skill's leading word first—the description is where it does its invocation work.
One trigger per branch. Synonyms that merely rename a single branch are duplication—"build features using TDD … asks for test-first development" is the same branch written twice. Merge them; keep only genuinely distinct branches.
Delete identity already in the body. The description should keep only triggers, plus the necessary "when another skill needs…" reach clause.

Information hierarchy

A skill is made of two kinds of content:steps and reference, freely mixed: a skill can be all steps, all reference, or both. The core decision is which kind of content to use, and which layer of the information hierarchy each piece of content goes in—a ladder ordered by how immediately the agent needs the material:

In-skill step - SKILL.md are the primary tier: what the agent does, in order. Each step ends with completion criterion , i.e. the condition that tells the agent the work is done. Make it checkable(can the agent tell done from not-done?), and where necessary exhaustive("every modified model is accounted for", not "produce a change list")—a vague criterion invites premature completion。
In-skill reference - SKILL.md definitions, rules, or facts, consulted as needed. Often a legitimate flat peer-set (all the rules for one review on a single rung)—this is not a bad smell.This skill is all reference.
External reference - from SKILL.md pushed into a separate file, via context pointer is reached, loading only when the pointer fires. (Covering disclosed reference—like GLOSSARY.md sibling files such as this, which are still part of the skill—to entirely outside the skill system, which any skill can point to external reference。）

A strong completion criterion will drive sufficient legwork—the digging the agent does while working—regardless of whether the skill has steps, because "every rule is applied" constrains flat reference, just as "every step is completed" constrains sequence.

Disclosing too little bloats the top level; disclosing too much hides material the agent actually needs. That tension is the whole decision.

Progressive disclosure is moving down the ladder—out of SKILL.md, into a linked file—keeping the top level clear. Mechanics: linked .md files in the skill folder, named after their content (this skill discloses the full definition into GLOSSARY.md). Some skills are used in more than one way, and each distinct way is a branch—different runs traverse the skill along different paths. Branching is the cleanest disclosure test: inline what every branch needs, and put behind a pointer what only some branches reach.Context pointer of wording, not the target file, determines when and how reliably the agent reaches the material.

The ladder determines how far down to move，co-location determines, once it is there, what sits beside it: put a concept's definition, rules, and caveats under the same heading rather than scattering them, so that reading one part brings its neighbors along.

When to split

Granularity is the granularity at which the skill is split, and each split costs one of the two kinds of load, so split only when the split pays off. Two ways to split:

By invocation - when you have an independent leading word should fire autonomously, or another skill must reach it, split out a model-invoked skill. You pay for the new always-loaded description Pay context load, so independent reach must be worth it.
By sequence - when a later steps(a step's post-completion steps) would tempt the agent to rush to finish the previous step (premature completion), split a chain of steps. Hiding them out of sight encourages the agent to do more on the current task legwork。

Pruning

Give every meaning a single source of truth: one authoritative location, so that changing behavior is a single edit.

Check line by line relevance: does it still support the skill's work?

Then look sentence by sentence for no-ops, not just line by line: no-op test each sentence on its own; when it fails, delete the whole sentence rather than just trimming words. Be aggressive—most failing prose should be deleted, not rewritten.

Leading words

Leading word is a compact concept already present in the model's pretraining that the agent thinks with while running the skill (e.g. lesson、fog of war、tracer bullets). It recurs throughout the text (but not necessarily—a strong leading word may need only one occurrence), accumulates a distributed definition, and anchors an entire swath of behavior with minimal tokens by recruiting priors the model already holds.

It serves predictability twice. In the body it anchors execution: every time the agent encounters the word, it triggers the same kind of behavior. In the description it anchors invocation: When the same word exists in your prompts, docs, and codebase, the agent connects that shared language to the skill and triggers it more reliably.

Look for opportunities to refactor skills to use leading words. A triad repeated in three places (duplication), a description that spends a sentence circling a concept—each passage is a plea to turn collapse into a single token. For example:

"fast, deterministic, low-overhead" -> tight—a quality stated repeatedly across one stage—into a pretrained word (a tight loop）。
"a loop you believe in" -> red—converting a vague gate into a binary observable state (the loop turns redon the bug, or it doesn't).

You win fewer tokens at the same time,and a sharper hook lets the agent hang its thinking on it. Assume every skill carries repeated statements that leading words can retire—go find them.

Failure modes

Use these to diagnose problems users may encounter when using a skill.

Premature completion - Ends before the current step is truly complete, with attention sliding toward being done. Defense order: first sharpen the completion criterion (cheap, local); only when it is inevitably vague and you observe rush, split out hidden post-completion steps (sequence cut).
Duplication - The same meaning appears in multiple places. It raises maintenance cost, wastes tokens, and inflates that meaning's prominence on the ladder beyond its true rank.
Sediment - Stale layers deposited because adding seems safe and deleting seems risky. The default fate of any skill lacking pruning discipline.
Sprawl - The skill is too long, even if every line is live and unique. It harms readability and maintainability and wastes tokens. The cure is the ladder: disclose reference behind pointers, split by branch or sequence, so each path carries only what it needs.
No-op - A line the model would do by default, so you pay the load and say nothing. Test: does it change default behavior? A weak leading word (such as be thorough, when the agent is already roughly thorough) is a no-op; the fix is a stronger word (such as relentless), not a different technique.
Negation - Guiding by prohibition backfires:don't think of an elephant names the elephant, making it easier to surface, not harder. Instead prompt positive—state the target behavior directly, so the prohibited behavior is never spoken; keep prohibition only for hard guardrails that cannot be expressed positively, and even then pair it with what should be done.