writing-for-agents

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

SKILL-MECHANICS.md

to learn about frontmatter, invocation options, and router skills.

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:

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

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.

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:

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.

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

The strongest criteria are both verifiable and exhaustive.

Splitting a document into two consumes one of the two loads, so only split if the cut earns back the cost:

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:

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.