writing-great-skills

The purpose of a Skill is to extract certainty from a random system.Predictability—that is, the Agent follows the sameprocessevery time it runs, rather than producing the same output—is the fundamental virtue; every lever below serves it.

Bold termsare defined in GLOSSARY.md ; consult that file for the full meaning.

Invocation method

Two choices, each with a different cost:

• Model-invoked skills keep description, so the Agent can trigger them autonomously,andother skills can also invoke them (you can also type the name directly). They add context load—the description exists in context every turn. Mechanism: omit disable-model-invocation, write a model-facing description containing rich trigger phrases ("use when the user wants to…, mentions…").
• User-invoked skills remove the description from the Agent's view: it can only be invoked if you type its name—other skills cannot invoke it either. Zero context load, but it consumes cognitive load：youmust remember it exists. Mechanism: set disable-model-invocation: true；description to be human-facing—a one-line summary, removing the trigger list.

Choose model invocation only when the Agent must invoke the skill autonomously, or when it must be invoked by other skills. If it is only triggered manually, make it user-invoked and do not pay the context load.

When you have so many user-invoked skills that you cannot remember them, the accumulated cognitive load can be solved with a router skill : a user-invoked skill that lists other skills and their applicable scenarios.

Writing the description

A model-invoked description does two jobs—stating what the skill is, and listing the branchesthat should trigger it. Every word adds context load, so the description should be trimmed even more aggressively than the body:

• Put the skill's core word first—the description is where it does its invocation work.
• One trigger word per branch. Synonyms are just duplicationof one branch—"build features using TDD… require test-first development" is writing the same branch twice. Merge them; keep only genuinely distinct branches.
• Delete information already in the body. Keep only trigger words in the description, plus a "when other skills need…" invocation clause.

Information hierarchy

A Skill is made of two content types—steps and reference—which can be mixed freely: a skill can be all steps, all reference, or both. The core decision is which type to choose, and where each piece of content goes in the information hierarchy The position in the ladder is ordered by how urgently the Agent needs the material:

1. Steps within the skill——SKILL.md The ordered operations in the skill, that is, the main content layer: the operations the Agent performs in sequence. Each step ends with a completion criterion , that is, the condition that tells the Agent the work is complete. Make itcheckable(can the Agent distinguish completion from non-completion?), and where necessary make itexhaustive("every modified model has been handled," not "generate a change list")—vague criteria lead to premature completion。
2. References within the skill——SKILL.md The definitions, rules, or facts in the skill, consulted as needed. They are usually a legitimately flat peer set (for example, all the review rules are at the same level)—this is a reasonable arrangement, not a bad smell.This skill is entirely reference.
3. External reference—content moved out of the SKILL.md into a separate file, accessed through a context pointer , and loaded only when the pointer triggers. (Includingdisclosedreferences—peer files within the skill such as GLOSSARY.md—all the way to fullyexternal references, that is, files located outside the skill system that any skill can point to.)

A demanding completion criterion can drive thorough legwork—the digging the Agent does during the work—regardless of whether the skill has steps, because "every rule has been applied" constrains a flat reference no less than "every step has been completed" constrains a sequence.

Push too little and the top level becomes bloated; push too much and you hide material the Agent actually needs. This tension is the whole decision.

Progressive disclosure is the operation of moving downward—from the SKILL.md into a linked file—keeping the top level clear. The mechanism: create a linked .md file in the skill folder, named after its content (this skill discloses its full definition into GLOSSARY.md). Some skills have multiple ways of being used, and each distinct way is a branch—a different execution path. Branches are the cleanest disclosure test: inline what every branch needs, and put behind a pointer what only some branches need.Context pointer'swording, rather than its target, determines when and how reliably the Agent retrieves that material.

The ladder determines how fardowna piece of content goes, while co-location determines, once it is placed,what is adjacent to it: put a concept's definition, rules, and caveats under the same heading rather than scattering them, so that reading one section also brings in its neighbors.

When to split

Granularity is how finely you divide the skill; every split consumes one of the two loads, so do it only when the split is worthwhile. Two ways to split:

• Split by invocation—when you have a distinct leading word should independently trigger this skill, or when another skill needs to call it, split it into amodel-invoked skill. For each newly added always-loaded description you pay context load, so this independent invocation must be worth it.
• Split in sequence—when later steps (a step's post-completion steps) tempt the Agent to rush the current step (premature completion), split a step sequence. Moving them out of view helps the Agent do more legwork。

Compression

Keep a single source of truthfor each meaning: one authoritative location, so changing behavior requires editing only one place.

Check each line's relevance: is it still relevant to the skill's function?

Then go sentence by sentence for no-op, not just line by line: run the no-op test independently on each sentence, and when a sentence fails, delete the entire sentence rather than trimming words within it. Be aggressive—most failing sentences should be deleted, not rewritten.

leading words

leading wordis a compact concept that already exists in the model's pretraining, which the Agent uses to think when executing the skill (for example, lesson、fog of war、tracer bullets). Appearing repeatedly throughout the text (though not necessarily—a strong leading word may need to appear only once), it accumulates a distributed definition with minimal tokens and anchors the entire behavior region by leveraging prior knowledge the model already has.

It serves predictability twice. In the body it anchorsexecution: the Agent invokes the same behavior every time it sees this word. In the description it anchorsinvocation: when the same word appears in your prompts, docs, and code, the Agent links this shared language to the skill and triggers it more reliably.

Look for opportunities to refactor the skill to use leading words. A triple described in detail in three places (repetition), or a description that spends a sentence pointing to some concept—each is a passage yearning to becollapsedinto a single token. Examples include:

• "fast, deterministic, low-overhead" -> tight —a quality reiterated across phases—collapsed into a pretrained word (a tight loop）。
• "the loop you trust" -> red —turning a fuzzy gate into a binary observable state (the loop goes redon bugs, or it doesn't).

You win twice: fewer tokens,anda sharper hook for the Agent to hang its thinking on. Assume every skill carries repetitive phrasing that leading words could replace—go find them.

Failure modes

Use these to diagnose problems users may encounter when using skills.

• premature completion — ending a step before it is truly complete, with attention sliding toward "done" rather than the work. Defenses, in order: first sharpen the completion criterion (cheap, local); only when the criterion is irreducibly vagueandyou actually observe haste, split out the hidden post-completion step (sequential cutting).
• Duplication — the same meaning appears in multiple places. It consumes maintenance cost and tokens, and elevates a meaning's importance on the ladder above its actual level.
• Sediment — layers of stale content that settle because adding feels safe and deleting feels risky. The default fate of a skill without pruning discipline.
• Sprawl — a skill that is too long, even if every line is valid and unique. It harms readability and maintainability and wastes tokens. The solution is information hierarchy: disclosereferencesbehind pointers, and split bybranchor sequence so that each path carries only what it needs.
• No-op — a line the model already follows by default, so you pay the load and say nothing. Test: does it change behavior compared with the default? A weak core word ("be thorough" when the Agent is already quite thorough) is a no-op; the solution is a stronger word ("ruthlessly"), not a different technique.
• Negation — instructions that tell the agent notto do something. A boundary is only worth anything if the agent might otherwise step into it; drawing a boundary where it would not go merely adds characters. Solution: check whether it is a hidden prohibitive branch that would never trigger at all, then delete it.