Provides guidance for any document consumed by agents — a skill, an
/
, or a document accessed via a pointer. The packaging differs; the writing itself does not: the same levers make each predictable — the agent follows the same
process on every run, rather than producing the same output.
When writing documentation for a skill, read
to learn about frontmatter, invocation options, and router skills.
Context Pointers
A
context pointer is a reference held in the agent's context that names material outside the context and encodes the conditions for accessing it. A skill's description is one example; a line in
that names a document is another instance. It's the
wording of the pointer, not its target, that determines when and how reliably the agent accesses the material. Content that must be targeted but is carried by a weakly worded pointer is a variance bug: refine the wording first, and only inline the material if refinement fails.
A pointer does two things — states what the material is, and lists the branches that should trigger access to it (a branch is an independent scenario in document processing, so different runs will follow different paths through it). Every word in a pointer that loads consistently incurs a cost on every run, so it deserves more aggressive pruning than the main text:
- Put leading words first — the pointer is where the triggering work happens.
- One trigger per branch. If synonyms merely rename a single branch, it's the same branch written twice; merge them and keep only truly distinct branches.
- Remove identities already carried by the main text.
The Two Loads
Every document and pointer you add consumes one of two budgets:
- Context load — the cost to the agent's window of material that loads consistently: a line in , a skill description, anything that stays in the context every run, incurs token and attention costs regardless of whether it's triggered.
- Cognitive load — the cost to humans: knowing which documents exist and when to retrieve each one. Humans are the index. This is not a cost to minimize — it's the price of human agency; spend it where human judgment matters, and remove it where it doesn't.
Material accessible only via a pointer avoids context load at the cost of the pointer's own line; material with no pointer at all is entirely carried by cognitive load.
Information Hierarchy
A document consists of two types of content — steps (ordered actions the agent performs) and reference (definitions, rules, facts consulted on demand) — which mix freely: all steps (a recipe), all reference (review rules, this skill), or a mix of both. The core decision is where each piece of content sits in the information hierarchy — a ladder ordered by how immediately the agent needs the material:
- In-file step — primary tier: what the agent does in sequence.
- In-file reference — consulted on demand. Often a valid flat peer-set (all rules for a review are on the same rung) — this is a reasonable arrangement, not a code smell.
- Disclosed reference — moved to a separate file, accessed via a context pointer, and only loaded when the pointer triggers. Covers both sibling files in the same folder and fully external references that exist anywhere and can be linked to by any document.
Moving too little content down bloats the top tier; moving too much hides material the agent actually needs. That tension is the entire decision.
Progressive disclosure is the act of moving down the ladder — removing content from the main file and placing it behind a pointer — to keep the top tier clear. It's not primarily a token optimization: it's how the hierarchy is protected. Branching is the cleanest disclosure test: inline content needed by every branch, and only place content accessed by some branches behind a pointer. When a document has steps, in-file reference that should be disclosed buries them, making attention to them a coin flip — this is a variance lever, not just a readability lever.
Co-location is the accompanying action within a file: the ladder determines how far down a piece of content moves, and co-location determines what sits beside it once there. Keep the definition, rules, and caveats of a concept under the same heading instead of scattering them, so neighbors come along when reading part of it. The test: the document should read like documentation written specifically for agents — grouped material does this; scattered material does not. (This differs from duplication: duplication repeats the same meaning in two places; scattering fragments a single meaning across many places.)
Sprawl is the failure mode here: documents grow too long even if every line is live and unique. Attention thins across extraneous content, and every extra line requires more maintenance. The cure is the ladder: disclose reference behind pointers and split by branch or sequence, so each path carries only what it needs.
Steps and Completion Criteria
Every step ends with a completion criterion — the condition that tells the agent the work is done. Two properties make it a lever:
- Clarity — can the agent distinguish done from not-done? A fuzzy boundary ("understanding reached") induces premature completion: ending the step before it's truly finished, with attention shifting to being done. Visible subsequent steps — post-completion steps — provide pull; the clarity of the criterion is resistance. Defend in order: sharpen the boundary first (local and cheap); only hide subsequent steps by splitting the sequence when the boundary is inevitably fuzzy and you observe rushing — and hiding only works when crossing a real context boundary (a hand-off or subagent dispatch; inline calls leave subsequent steps in the context and clear nothing).
- Demand — how much it requires. "Every modified model accounted for" forces thorough work, while "produce a change list" does not. Demand drives legwork — the digging the agent does internally during the work, hidden in wording rather than written as its own step — and it's not constrained by steps: "every rule applied" binds a set of flat reference, just as "every step done" binds a sequence, which is why a fully reference-based document still carries a threshold of exhaustiveness.
The strongest criteria are both verifiable and exhaustive.
When to Split
Splitting a document into two consumes one of the two loads, so only split if the cut earns back the cost:
- By sequence — split a chain of steps when post-completion steps tempt the agent to rush through the current step. Hiding them from view drives more legwork on the current task. Beware the reverse: merging sequences exposes each step's subsequent steps to what comes after, inducing premature completion.
- By invocation — skill-specific: see .
Leading Words
A leading word is a compact concept already present in the model's pre-training that the agent uses to think when running the document (lesson, fog of war, tracer bullets). It repeats as a token, never as a sentence, accumulates a distributed definition, and anchors a whole range of behavior with minimal tokens by recruiting priors the model already holds. Coining your own words is allowed as long as you define them clearly, but a made-up word recruits no priors — you pay for the definition what a pre-trained word provides for free; reach for an existing word first.
It anchors twice. In the main text, it anchors execution: every time the word appears, the agent reaches for the same behavior, and within flat reference it focuses attention on the type of thing to look for. In a pointer, it anchors invocation: when the same word exists in your prompts, docs, and codebase, the agent connects that shared language to the material, accessing it more reliably.
Look for opportunities to refactor with leading words. A triad expanded in three places, a pointer that takes a sentence to point to a concept — each is text begging to collapse into a single token:
- "fast, deterministic, low-overhead" → tight (a tight loop).
- "a loop you believe in" → red — a fuzzy gate becomes a binary observable state (the loop goes red on bugs, or it doesn't).
You win twice: fewer tokens, and a sharper hook for the agent to hang its thinking on. Assume every document carries restatements that leading words can retire — look for them.
Negation is the failure mode beside this lever: guiding with prohibitions drags the forbidden behavior into the context, making it more likely to emerge, not less. Don't think of an elephant, and the elephant is all you can think of; negation is a weak modifier overwhelmed by a strongly activated concept, so prohibitions read half like instructions to do the thing. Prompt positively — state the target behavior directly ("write one-line comments") so the forbidden one is never mentioned. Only use prohibition when you can't express a hard guardrail positively; even then, pair it with a positive goal to focus attention on what to do.
Pruning
- Keep each meaning in a single source of truth: an authoritative location, so changing behavior is a single edit. Duplication — the same meaning appearing in multiple places — incurs maintenance and token costs, and elevates the meaning's prominence in the ladder beyond its true level. (This is the intentional counterexample for leading words — leading words repeat a token intentionally, never the meaning.)
- The environment is also a source of truth — scripts, config files, directory layout, output — and a document that restates it is a cache: a copy of a lookup, which only deserves its load if the lookup is expensive. Cache things the agent can't find by checking the environment: unwritten conventions, the reasoning behind a choice, gotchas no config will admit. Leave one-file, one-command lookups to the environment, where they won't become outdated.
- Check relevance line by line: does it still support the document's purpose? A line loses relevance either because it never supported the task (just expository, or a branch that should have been disclosed) or because the behavior or world it describes has become stale. Shorter documents are easier to keep relevant. Without pruning discipline, the default fate is sediment: stale layers accumulated because adding feels safe and deleting feels risky, until you have to drill through them to find what's still live.
- Look for no-ops sentence by sentence: an instruction the model would follow by default, incurring load but saying nothing. The test — does it change behavior relative to the default? — is model-relative, not reader-relative: if two people disagree on a no-op, they're disagreeing on the default; resolve it by running the document, not debating. When a sentence fails, delete the whole sentence, not just trim words. This test also applies to scoring leading words: a word too weak to beat the default (be thorough when the agent is already roughly thorough) is a no-op; fix it by replacing it with a stronger word (relentless), not changing techniques.