writing-for-agents

A reference for writing any documentation an agent reads: a skill, a AGENTS.md / CLAUDE.md, a document reached through a pointer. The packaging varies, but the writing rules are the same: the same levers make every document predictable, because the agent takes the sameprocesson every run, rather than producing the same output.

When the document you are writing is a skill, read SKILL-MECHANICS.mdfor frontmatter, choosing the invocation method, and routing skills.

Context pointers

A context pointer is a reference held in the agent's context that points to material "outside the context" and encodes the conditions for reaching that material. A skill's description is one;AGENTS.md a line in a document pointing to some documentation is the same thing. What determines when and how reliably the agent reaches this material is the pointer'swording, not what it points to. A target that should be reached but is hidden behind vaguely worded pointer: this is a variance bug: polish the wording first; only when polishing fails, inline the material directly.

A pointer carries two things: saying what this material is, and listing thebranchesthat should trigger reaching it (a branch is a distinct situation this document handles, so different runs take different paths). Every word in a pointer that is always loaded pays a cost on every turn, so it needs stricter trimming than the body:

• Move the "leading word" forward: the pointer is where the triggering work actually happens.
• One branch corresponds to one trigger word. Synonyms write the same branch in two different ways; essentially one branch; merge them and keep only the truly distinct branches.
• Remove identity information already carried by the body.

Two kinds of load

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

• Context load: the cost of always-loaded material occupying the agent's window: one line of AGENTS.md, one skill description, anything that always stays in context and consumes tokens and attention whether or not it is triggered.
• Cognitive load: the cost borne by humans: which documents exist and when each is used. Humans are this index. It is not a cost to be minimized: it is the price of human agency; spend it where human judgment is needed, and remove it where it is not.

Material reached only through a pointer escapes context load, at the cost of the pointer's own line; material with no pointer at all relies entirely on cognitive load.

Information hierarchy

A document consists of two content types:Steps(actions the agent performs in order) andreference(definitions, rules, facts consulted as needed). The two can be mixed freely: all steps (a how-to guide), all reference (a review rule, like this skill), or both. The core decision is: where should each piece of content goInformation hierarchyWhich level of it? This is a ladder sorted by "how immediately the agent needs the material":

1. In-file step is the primary level: what the agent does in sequence.
2. In-file reference consulted on demand. It is often a reasonable flat peer set (one review rule is one level), and this is a sound arrangement, not a bad smell.
3. Disclosed reference is pushed out into a separate file, reached through a context pointer, and loaded only when that pointer is triggered. The span can range from an adjacent file in the same folder to a fully external reference placed anywhere: any document can point to it.

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

Progressive disclosure is the process of moving down this ladder (out of the main file, behind a pointer) in order to keep the top level clearly readable. It is not mainly about optimizing tokens: it is the means of protecting this hierarchy. Branching is the cleanest disclosure test: inline what every branch needs, and push behind a pointer what only some branches will reach. When a document has steps, in-file references that should have been disclosed will bury them, making it a matter of luck whether they are noticed: this is a variance lever, not just a readability lever.

Co-location is the companion concept within a file: the hierarchy determines howdeepa piece of content goes, and co-location determines, once it is placed there,what content sits alongside it. Put a concept's definition, rules, and cautions under the same heading instead of scattering them, so that when one is read, the content next to it also enters view. The test is: this document should read like a document written for an agent. Material gathered together reads that way; scattered material does not. (This is a different concept from "repetition": repetition says the same meaning twice; scattering breaks one meaning into multiple pieces.)

Sprawl is the failure mode here: a document that is simply too long even if every line is live and unique. Attention thins out in redundancy, and every extra line adds to the burden of maintaining relevance. The remedy is this ladder: disclose references through pointers, and split by branch or sequence so that each path carries only what it needs.

Steps and completion criteria

Each step ends with acompletion criterion: the condition that tells the agent "the work is done." Two properties make it a lever:

• Clarity: Can the agent distinguish complete from incomplete? A vague boundary (such as "achieve understanding") invitespremature completion: ending before this step is truly complete, as attention slides toward "the state of completion." Steps still visible ahead (subsequent steps) provide pull; the clarity of the completion criterion is the resistance. Defend in order:first polish the boundary(local and cheap); only when it is inherently vague,andOnly when you observe the rush-to-completion phenomenon do you hide subsequent steps by splitting their order. Hiding is effective only when crossing a real context boundary (a handoff or a subagent dispatch; an inline call leaves subsequent steps in context, clearing nothing).
• Demand: how much it requires. "Every modified model is logged" forces more thorough work than "produce a change list." Demand driveslegwork: the digging the agent does within the work, lurking in the wording rather than written as a separate step: and it is not step-bound: "every rule applied" constrains a whole flat reference, just as "every step completed" constrains a sequence, which is why a document of all references still carries the standard of "exhaustiveness."

The strongest completion criteria are both testable and exhaustive.

When to Split

Splitting a document into two spends one of two loads, so split only when the split "earns its keep":

• Split by Order: when in a sequence of steps, a later completion step tempts the agent to wrap up before the step before it, split it apart. Keeping subsequent steps out of view forces the agent to do more legwork on the current task. Beware the reverse operation: merging sequences exposes each step's "subsequent steps" before what happens next, tempting early completion.
• Split by Invocation Method: skill-specific cuts, see SKILL-MECHANICS.md。

Leading Words

Leading word is a compact concept already present in the model's pretraining, the word the agent thinks with when executing this document (lesson、fog of war、tracer bullets). It is used repeatedly as a token: not a sentence: accumulating a distributed definition with minimal tokens, and anchoring a whole swath of behavior by invoking prior knowledge the model already holds. Coining a new word is fine, provided you define it clearly; but a coined word attracts no priors: you have to pay with definition tokens for what a pretrained word gives you for free; look for an existing word first.

It anchors twice. In the body text,execute: each time this word appears, the agent evokes the same behavior; within a flat reference, it focuses attention on a class of things to look for. In a pointer,invoke: when the same word appears simultaneously in your prompt, document, and codebase, the agent associates this shared language with that material and reaches it more reliably.

Actively look for opportunities to refactor with leading words. A triple expanded in three places, a pointer hinting at an idea in one sentence. Each is begging to be compressed into a token:

• "fast, deterministic, low-overhead" → tight(a tight loop).
• "a loop you believe in" → red, turning a fuzzy gate into a binary observable state (the loop goes redon a bug, or not red）。

You win twice: fewer tokens, and you give the agent a sharper "hook" to hang its thinking on. Assume every document carries some paraphrase a leading word can replace. Go find them.

Negation is the failure mode next to this lever: leading with a prohibition drags the prohibited behavior into context, making itMorereachable, not less. "Don't think of an elephant," and the elephant appears; negation is a weak modifier, overridden by the strongly activated concept, so a prohibition gets half-read as "do this thing." Preferpositivephrasing: state the target behavior (e.g. "write single-line comments"), so that the forbidden one never gets said at all. A prohibition earns its place only when it cannot be phrased positively; even then, pair it with the positive target so attention lands on "what to do."

Prune

• Give each meaning onesingle source of authority: one authoritative place, so changing the behavior changes one place.Duplication(the same meaning appearing in more than one place) costs both maintenance and tokens, and inflates a meaning's hierarchical prominence beyond its true rank. (This is the accidental inverse of the "leading word": a leading word intentionally repeats a token and never repeats a meaning.)
• The environmentis also a source of authority (package.json scripts, configuration files, directory layout,--help output), and documentation that restates the environment is acache: a copy of a "lookup" that pays off only when that lookup is expensive. Cache what an agent cannot get by looking it up: unwritten conventions, the reasons behind choices, little pitfalls the configuration won't confess. Leave lookups that a "single file, single command" can answer to the environment itself, which never goes stale.
• Checkrelevanceline by line: is this line still supporting what this document is meant to do? A line loses relevance either because it never truly took on this task (mere exposition, or a branch that should have been disclosed), or because the behavior or world it describes has changed, leaving it stale. Shorter documents are easier to keep relevant. Without pruning discipline, the default fate issediment: stale layers settling one on another, because "adding" feels safe and "deleting" feels risky, until you have to drill through them to find what is still alive.
• Huntno-opssentence by sentence: an instruction the model already follows by default, whose payload says nothing but empty words. The test ("does this instruction change behavior relative to the default behavior?") is relative to the model, not to the reader: two people who disagree about a no-op are really disagreeing about the default behavior, and that should be resolved by running the document, not by arguing. When a sentence fails, delete the whole sentence, rather than shaving a few words off it. The test also rates leading words: a word too weak to beat the default behavior ("be thorough," when the agent is already more or less thorough) is a no-op, and the fix is a stronger word (relentless), not a different trick.