Writing For Agents

Writing for Agents

The packaging differs across a skill, a CLAUDE.md, or a doc reached by a pointer — the writing discipline doesn't. The goal isn't a document a human reads once; it's a document that gets an agent to the same process every run, not just the same output.

Context pointers

A context pointer is a reference living in the agent's always-loaded context (a skill description, a CLAUDE.md line) that names material and encodes when to reach it. The pointer's wording — not its target — decides whether the agent actually reaches the material, and how reliably.

• Front-load the trigger word — the pointer does its work at the start, not buried in a clause.
• One trigger per distinct case. Synonyms restating the same case are the same branch written twice — collapse them.
• Cut identity the target document already states — don't restate the material in the pointer.

Two budgets, spent differently

• Context load — the cost of always-loaded material (a skill description, a CLAUDE.md line) on every single turn, whether or not it fires.
• Cognitive load — the cost on the human of knowing which documents exist and when to reach for each. Not a cost to eliminate — it's the price of human judgment; spend it where the judgment matters, remove it where it doesn't.

Material behind a pointer pays only the pointer's cost in context load; material with no pointer rides entirely on someone remembering it exists.

Information hierarchy — where each piece of content sits

1. In-file step — what the agent does, in order. The primary tier.
2. In-file reference — consulted on demand, but still in the main file (e.g. a flat rule list).
3. Disclosed reference — pushed to a separate file, reached only through a pointer, loaded only when it fires.

Push too little down and the top of the document bloats past what every run needs; push too much down and material the agent actually needs stays hidden. Progressive disclosure is moving material down this ladder as it stops being universally needed — the branching test: inline what every path needs, disclose what only some paths reach.

Co-location: keep a concept's definition, rules, and caveats under one heading rather than scattered across the document, so reading one part brings its neighbors with it.

Leading words

A leading word is a compact, already-understood term (seam, tracer bullet, red/green) that anchors a whole region of behavior in a few tokens by recruiting priors the model already has, instead of restating a description every time. Reuse an existing well-known term before coining a new one — a made-up word carries no priors, so you pay in definition tokens what a pretrained word gives free.

Avoid steering by negation ("don't do X") — naming the forbidden behavior makes it more available to the model, not less. State the positive target instead ("write one-line comments," not "don't over-comment").

Pruning

• Single source of truth. The same meaning stated in two places is duplication — costs upkeep, and inflates that meaning's apparent importance.
• Don't restate the environment. package.json scripts, config, --help output are sources of truth on their own; a doc that copies them is a stale cache waiting to happen. Document the unwritten convention or the reason behind a choice — not what a one-command lookup already answers.
• Check relevance regularly. A line that no longer bears on the task, or has gone stale as the world changed, should go. Without this habit, documents accumulate sediment — old layers nobody wants to be the one to delete.
• Cut no-ops. An instruction the agent already does by default costs tokens for nothing. If it doesn't change behavior, delete the sentence.

Skills specifically: model-invoked vs. user-invoked

• Model-invoked — has a description the agent can match against context; the agent decides when to reach for it. Always costs a little context load (the description), in exchange for auto-discovery.
• User-invoked (disable-model-invocation: true) — only reached when the user explicitly types it. Zero ongoing context load, at the cost of the human having to remember it exists.
• Router skill — a user-invoked skill that's just an index of other user-invoked skills, so the human doesn't have to hold that whole list in their own head.

Pick model-invoked for anything the agent should apply by default (a discipline, a standard); user-invoked for anything expensive, destructive, or only useful when deliberately asked for — matches how design-lab (manual) vs. prototype (auto-triggers) are split in this repo.

See also

• creating-skills — the meta-skill for generating a new skill's structure. This skill is the writing discipline underneath it: creating-skills decides what a skill contains, writing-for-agents decides how any of it should be worded.
• products/ald-os/context/product-builder-principles.md — Engineering #14, Documentation is part of the deliverable. This skill is that principle's operational form.

Source

Adapted from mattpocock/skills' writing-for-agents and SKILL-MECHANICS.md.