writing-for-agents

Provide a reference for any documentation an agent consumes: a skill, a AGENTS.md / CLAUDE.md, a document reached via a pointer. The packaging differs; the writing itself does not: the same levers make each one predictable: the agent takes the same processon every run, rather than producing the same output.

When the document you are writing is a skill, read SKILL-MECHANICS.md to learn about frontmatter, invocation choices, and router skills.

Context pointers

context pointer is a reference held in the agent's context that names material outside that context and encodes the conditions for reaching it. A skill's description is one;AGENTS.md a line naming a document is the same object. What determines when and how reliably the agent reaches the material is the pointer's wording, not its target. Content that must be a target but is carried by a weakly worded pointer is a variance bug: polish the wording first, and inline the material only if polishing fails.

A pointer does two things: it states what the material is, and it lists the branchesthat should trigger reaching it (a branch is a distinct case of document handling, so different runs take different paths through it). Every word of an always-loaded pointer costs on every turn, so it should be pruned harder than the body:

Put the leading word first: the pointer is where it does the triggering work.
One trigger per branch. If synonyms merely rename a single branch, that is the same branch written twice; merge them and keep only the genuinely distinct branches.
Delete identity the body already carries.

Two kinds of load

Every document and pointer you add spends one of two budgets:

Context load: the cost of always-loaded material to the agent window: a line of AGENTS.md, a skill description, anything that sits in context every turn, costs tokens and attention whether or not it triggers.
Cognitive load: the cost to humans: which documents exist, when to reach for each one. Humans are the index. This is not a cost to minimize; it is the price of human agency; spend it where human judgment matters, and remove it where it does not.

Material reachable only through a pointer escapes context load at the cost of that pointer's own line; material with no pointer at all is carried entirely by cognitive load.

Information hierarchy

A document consists of two kinds of content:steps(ordered actions the agent performs) and reference(definitions, rules, facts consulted on demand), freely mixed: all steps (a recipe), all reference (the rules of a review, this skill), or both. The core decision is where each piece of content goes on the information hierarchy ladder, a ladder ordered by how immediately the agent needs the material:

In-file step(primary tier): what the agent does in order.
In-file reference: consulted on demand. Usually a legitimate flat peer-set (all the rules of a review on one rung), which is a reasonable arrangement, not a bad smell.
Disclosed reference: Push it out into a separate file, reached via a context pointer, loaded only when the pointer is triggered. This covers both sibling files in the same folder and fully external references that exist anywhere and can be pointed to by any document.

Pushing too little content down bloats the top level; pushing too much content down hides the material the agent actually needs. That tension is the whole decision.

Progressive disclosure is the act of moving down the ladder (out of the main file, behind a pointer), keeping the top level clear. It is mainly not a token optimization: it is how the hierarchy is protected. Branching is the cleanest disclosure test: inline what every branch needs, and put behind a pointer only what some branches reach. When a document has steps, an in-file reference that ought to be disclosed buries them, turning caring about them into a coin flip—a variance lever, not just a readability lever.

Co-location is the companion act within a file: the ladder decides how far down a piece of content moves down, and co-location decides once it gets there what is next to it. Put a concept's definition, rules and caveats under the same heading rather than scattered about, so that reading one part brings its neighbors along. The test: the document should read like documentation written specifically for an agent: grouped material reads that way; scattered material does not. (It differs from duplication: duplication repeats the same meaning in two places; scattering fragments one meaning across many.)

Sprawl is the failure mode here: a document that is too long, even if every line is live and unique. Attention thins out on redundant content, and every extra line must be maintained. The cure is the ladder: push reference behind pointers, and split by branch or sequence so that each path carries only what it needs.

Steps and completion criteria

Every step ends with a completion criterion : it tells the agent the condition under which the work is done. Two properties make it a lever:

Clarity: can the agent tell done from not-done? A vague boundary ("understanding reached") invites premature completion: ending before the step is truly complete, with attention sliding toward being done. Still-visible follow-on steps (post-completion steps) provide pull; the criterion's clarity is the resistance. Defend in order:first sharpen the boundary(local and cheap); only when it is inevitably vague and you observe rush, hide the follow-on steps by splitting the sequence, and hiding works only when it crosses a real context boundary (a hand-off or subagent dispatch; an inline call leaves the follow-on steps in context and clears nothing).
Demand: how much it demands. "Every modified model accounted for" forces thorough work, whereas "produce a change list" does not. Demand drives legwork(the digging the agent does inside the work, lurking in the wording rather than written as its own step), and it is not bound by step: "every rule applied" constrains a whole flat reference just as "every step done" constrains a sequence, which is why a document that is all reference still carries a threshold of exhaustiveness.

The strongest criteria are both checkable and exhaustive.

When to split

Splitting a document into two costs one of the two loads, so split only when this cut earns back its cost:

By sequence: when post-completion steps would tempt the agent to rush to end the current step, split a series of steps. Keeping them out of sight drives more legwork on the current task. Beware the reverse: merging sequences exposes each step's subsequent steps to what comes after it, inducing premature completion.
By invocation, skill-specific: see SKILL-MECHANICS.md。

Leading words

leading word is a compact concept that already exists in the model's pretraining, and the agent thinks with it while running the document (lesson、fog of war、tracer bullets). It appears repeatedly as a token, never as a sentence, accumulates a distributed definition, and anchors a whole swath of behavior with the fewest tokens by recruiting priors the model already holds. Coining your own term is also fine, as long as you define it clearly, but a made-up word recruits no priors, and you will pay in definition for what a pretrained word provides for free; reach first for an existing word.

It anchors twice. In the body it anchors execution: each time the word appears, the agent reaches for the same behavior, and within a flat reference it focuses attention on the class 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 and reaches it more reliably.

Look for opportunities to refactor with leading words. A triad spread across three places, a pointer that spends a sentence pointing to a concept, each passage is text begging to collapse into a single token:

"fast, deterministic, low-overhead" → tight(one tight loop）。
"a loop you believe in" → red: a fuzzy gate becomes a binary observable state (the loop turns redon the bug, 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, and go find them.

Negation is the failure mode next to this lever: guiding by prohibition drags the prohibited behavior into context, making it easier to surface, not harder.Don't think of an elephant, and the elephant is everything; negation is a weak modifier overwhelmed by a strongly activated concept, so a prohibition reads half like telling you to do that thing. Prompt should positive: state the target behavior directly ("write one-line comments"), so the prohibited one is never spoken. Only when you cannot express some hard guardrail positively does a prohibition deserve a place; even then, pair it with the positive goal so attention lands on what to do.

Prune

Keep every meaning in single source of truth: one authoritative location, so changing behavior is a single edit.Duplication(the same meaning appearing in multiple places) costs maintenance and tokens, and raises that meaning's prominence on the ladder above its true level. (This is the accidental converse of a leading word: a leading word intentionally repeats a token, never a meaning.)
environment is also a source of truth (package.json scripts, config files, directory layout,--help output), and a document that restates it is a cache: a copy of one lookup, earning its load only if the lookup is expensive. Cache what an agent cannot find by inspecting the environment: unwritten conventions, the reason behind a choice, the gotcha no config will confess. Leave one-file, one-command lookups to the environment, where they cannot go stale.
Check line by line relevance: does it still support the work the documentation does? A line loses relevance either by never supporting the task (merely expository, or a branch that should have been disclosed) or by going stale as the behavior or world it describes changes. Shorter documentation is easier to keep relevant. Without pruning discipline, the default fate is sediment: stale layers deposited because adding looks safe and deleting looks risky, until you must drill through them to find what is still live.
Sentence by sentence, look for no-ops: an instruction a model would obey by default, paying load while saying nothing. The test (does it change behavior relative to the default?) is model-relative, not reader-relative: two people disagreeing about a no-op are disagreeing about the default, settle it by running the documentation, not by debating. When a sentence fails, delete the whole sentence, not prune words from it. This test also grades leading words: a word too weak to beat the default (when the agent is already roughly thorough, be thorough) is a no-op, and the fix is a stronger word (relentless), not a different technique.