Writing For Agents

The document is a program with a fuzzy interpreter

Adapted from Matt Pocock's writing-for-agents (github.com/mattpocock/skills, MIT). The concept names below are his and worth keeping verbatim, because a shared name is the whole point of a leading word. What is added is this harness's measured numbers and the checks that already exist here.

This is a different axis from rules/writing-style.md. That governs prose a person reads. This governs how a document an agent executes is structured.

Context pointers

A context pointer is a reference sitting in the agent's context that names material it does not have, plus the condition for going and getting it. A skill's description is one. A line in CLAUDE.md naming a doc is the same object.

The pointer's wording, not its target, decides whether the material is ever reached. A must-have document behind a weakly worded pointer is not a documentation gap, it is a variance bug: it works on some runs. Sharpen the wording first; inline the material only when sharpening fails.

So a description is a trigger, not a summary. Name the situation the agent will be in, not the category the document belongs to.

npm run check:triggers measures this across every skill here: it flags descriptions naming no condition, and prints the standing cost of the set.

The two loads

Every pointer and document spends one of two budgets:

• Context load — always-loaded material, paid every turn whether or not it fires. Measured here: 13,886 bytes, about 3,472 tokens across 56 skill descriptions, resident in every session on this machine. That is the real price of "just add another skill", and it is why a description earns harder pruning than the body it points at.
• Cognitive load — the cost on the human of knowing which documents exist. Not a cost to drive to zero: it is the price of human agency. Spend it where judgement matters.

Information hierarchy

Rank each piece by how immediately the agent needs it:

1. In-file step — what the agent does, in order.
2. In-file reference — consulted on demand. A flat peer-set of rules is a legitimate shape, not a smell.
3. Disclosed reference — pushed behind a pointer, loaded only when it fires.

Progressive disclosure is the move down that ladder. The test is branching: inline what every run needs, disclose what only some runs reach. Push too little and the top bloats; push too much and you hide what the agent actually needs.

Sprawl is the failure mode — a document too long even when every line is live. Attention thins across the excess.

Completion criteria

Every step ends on a condition telling the agent it is done, and two properties make that a lever:

• Clarity — can it tell done from not-done? A vague bound invites premature completion, where attention slides to being finished. Sharpen the bound first; that is local and cheap.
• Demand — how much it asks. "Every modified model accounted for" forces legwork that "produce a change list" does not.

The strongest criteria are checkable AND exhaustive. This is the same instinct as rule-gate-integrity: a gate that prints a population is partly self-verifying, one that prints a verdict is indistinguishable from a probe that found nothing.

Leading words

A leading word is a compact concept already in the model's pretraining that the agent thinks with while running the document. Repeat it as a token, never as a sentence, and it anchors a region of behaviour cheaply by recruiting priors the model already holds. Coining your own works only if you define it, and you pay in definition tokens what a pretrained word gives free.

This harness already runs on them: frontier, blast radius, population, known-positive, mutation, the answer is zero. Each retired a paragraph.

Negation is the failure mode beside it. Steering by prohibition drags the forbidden behaviour into context and makes it MORE available. Prompt the positive: state the target so the banned thing is never spoken. Keep a prohibition only as a hard guardrail, and pair it with the positive target.

Pruning

• Single source of truth. The same meaning in two places costs maintenance and inflates its apparent rank.
• The environment is a source of truth. package.json scripts, config, the directory layout, --help. A document restating them is a cache, and a cache earns its load only when the lookup is expensive. Cache what cannot be looked up: the unwritten convention, the reason behind a choice, the gotcha no config confesses.
• Hunt no-ops. An instruction the model already follows by default pays load to say nothing. The test is model-relative and settled by RUNNING the document, not by argument. Delete the whole sentence rather than trimming it.

One addition, specific to briefs

A claim written into a subagent's brief is not a claim, it is built work. A wrong steer to a person costs a correction; the same steer to an agent costs a branch. So mark which parts of a brief are DECIDED and which are PROPOSALS — an agent cannot tell them apart from tone, and confident prose reads as decided.