Skills exist to extract determinism from stochastic systems. Predictability is the core virtue: the agent follows the same process every time, rather than producing the same output. All the levers below serve this goal.
Bold terms are defined in
; refer to it for full meanings.
Invocation
Two options, with different costs:
- Model-invoked skills retain their description, so the agent can trigger it autonomously, and other skills can also access it (users can still manually input the name). It incurs context load: the description stays in the context window every round. Mechanism: Omit , and write a model-facing description with rich trigger phrasing ("Use when the user wants...", "mentions...").
- User-invoked skills remove the description from the agent's reach: it can only be called when the user inputs the name, and other skills cannot invoke it either. Zero context load, but incurs cognitive load: the user must remember it exists. Mechanism: Set
disable-model-invocation: true
Choose model-invoked only when the agent must find the skill on its own, or another skill needs to call it. If it will only be triggered manually, make it user-invoked to avoid paying context load.
When there are too many user-invoked skills for users to remember, solve the cognitive load with a router skill: a user-invoked skill responsible for naming other user-invoked skills and when to use them.
Writing the description
Model-invoked descriptions do two things: explain what the skill is, and list the branches that should trigger it. Every word increases context load, so descriptions need more pruning than the main text:
- Put the skill's leading word first.
- One trigger per branch. Synonyms that only rename a single branch are duplication; merge them.
- Remove identity already present in the main text. The description only retains triggers and the necessary "when another skill needs..." reach clause.
Information hierarchy
Skills consist of two types of content: steps and reference. They can be all steps, all reference, or a mix of both. The core decision is which layer of the information hierarchy to place the content in:
- In-skill step - Ordered actions in , the primary tier. Each step ends with a completion criterion. The criterion should be verifiable and exhaustive if necessary.
- In-skill reference - Definitions, rules, or facts in , accessed on demand.
- External reference - Pushed from to an independent file, accessed via a context pointer.
Strong completion criteria drive sufficient legwork. Putting too little content lower down bloats the top layer; putting too much content lower down hides materials the agent actually needs.
Progressive disclosure is moving reference content down to linked files to keep the top layer clear. Mechanics: Linked
files in the skill folder, named after their content. Each use case of a multi-purpose skill is a
branch: content needed by all branches is inline, content needed only by some branches is placed after a pointer. The wording of the
context pointer, not the target file, determines when and how reliably the agent accesses the material.
Co-location determines where content is placed once moved down: keep the definition, rules, and caveats of a concept under the same heading, rather than scattered.
When to split
Granularity refers to how skills are split. Each split incurs one of the two types of load, so only split when there is a benefit.
- By invocation - Split out a model-invoked skill when you have an independent leading word that should trigger autonomously, or another skill needs to access it. You pay context load for the new description, so independent access must be worthwhile.
- By sequence - Split the step sequence when subsequent steps tempt the agent to finish the previous step early (premature completion), hiding the later content.
Pruning
Give each meaning a single source of truth: an authoritative location where changes are made in only one place when behavior changes.
Check relevance line by line: Does it still support the skill's function?
Then look for no-ops sentence by sentence. Test each sentence individually for being a no-op; delete the entire sentence if it fails, rather than just trimming words. Be aggressive; most failing prose should be deleted, not rewritten.
Leading words
A leading word is a compact concept already present in the model's pre-training, which the agent uses to think while running the skill (e.g., lesson, fog of war, tracer bullets). It repeats in the text, accumulates a distributed definition, and anchors a set of behaviors with minimal tokens.
It serves predictability in two ways. In the main text, it anchors execution; in the description, it anchors invocation. When the same word appears in prompts, docs, and codebase, the agent can more easily connect the shared language to the skill.
Look for opportunities to refactor skills to use leading words. Triads that are expanded three times, descriptions that take a sentence to circle a concept, can potentially collapse into a single token. For example:
- "fast, deterministic, low-overhead" -> tight
- "a loop you believe in" -> red
You gain both fewer tokens and a sharper thinking hook.
Failure modes
- Premature completion - Ending a step before it is truly finished. Defense sequence: First sharpen the completion criterion; only hide post-completion steps by splitting when the criterion is inevitably vague and you observe rushing.
- Duplication - The same meaning appears in multiple places. It increases maintenance costs, wastes tokens, and exaggerates the importance of the meaning in the hierarchy.
- Sediment - Stale layers accumulated because adding seems safe and deleting seems risky.
- Sprawl - The skill is too long, even if every line is live and unique. Treat with hierarchy: Move reference content behind pointers, split by branch or sequence.
- No-op - Instructions that the model would do by default. Test: Does it change default behavior? Weak leading words (e.g., be thorough, when the agent is already roughly thorough) are no-ops; fix by replacing with stronger words (e.g., relentless).