Writing Rules

Writing rules — and anything else an agent reads

You are writing for a reader who has already read everything. Explanation is waste; precision is the whole job. Left alone, a model writing instructions for a model spends most of its words restating what it already knows — every one of those lines is a no-op: paid every turn, changing nothing.

The packaging differs (a core/ rule, a profile gate, a SKILL.md, a subagent prompt, a handoff note) but the writing does not. The same levers make each one predictable, so the agent takes the same process every run rather than producing the same output.

When the document is a harness surface — a core/ rule, a profile, a skill, a hook — read HARNESS-SURFACES.md for where it goes and what it costs.

Instruction vocabulary

AGENTS.md is the canonical portable instruction file. Never infer the active agent from this skill's install path: portable canonical content may be copied into a required client adapter such as .claude/skills. Treat client-specific instruction files as generated adapters; edit their shared core/ or profiles/ source, never an adapter copy.

The two loads

Every document and every pointer spends one of two budgets. Most authoring decisions are this one trade made in different places:

• Context load — what always-loaded material costs the agent's window: an instruction-file line, a skill description, anything sitting in context every turn whether or not it fires.
• Cognitive load — what it costs you: knowing which documents exist and when to reach for each. You are the index. Not a cost to minimise — it's the price of human agency. Spend it where human judgement matters; remove it where it doesn't.

Material behind a pointer escapes context load for the price of the pointer's own line. Material with no pointer at all rides entirely on cognitive load.

Context pointers

A context pointer is a reference held in context that names out-of-context material and encodes when to reach it. A skill's description and an instruction-file line naming a doc are the same object. The pointer's wording, not its target, decides how reliably the agent reaches through it — so a must-have target behind a weak pointer is a variance bug. Sharpen the wording first; inline the material only if sharpening fails.

A pointer does two jobs: say what the material is, and list the branches that should trigger it (a branch is a distinct case the document handles). Every word is paid every turn, so prune it harder than the body:

• Front-load the leading word — the pointer is where it does its triggering work.
• One trigger per branch. Synonyms renaming one branch are one branch written twice.
• Cut identity the body already carries.

The ladder — where each piece sits

Documents are built from steps (ordered actions) and reference (facts consulted on demand). They mix freely: all steps, all reference, or both. The decision is how far down each piece sits:

1. In-file step — what the agent does, in order. The primary tier.
2. In-file reference — consulted on demand. Often a legitimately flat peer-set (every gate of a profile on one rung). That's an arrangement, not a smell.
3. Disclosed reference — a separate file behind a pointer, loaded only when the pointer fires.

Progressive disclosure is the move down that ladder so the top stays legible. Branching is the cleanest test: inline what every branch needs; disclose what only some branches reach. Push too little down and the top bloats; push too much and you hide what the agent actually needs.

Co-location is the within-file companion — the ladder decides how far down, co-location decides what sits beside it. Keep a concept's definition, rules and caveats under one heading so reading one part brings its neighbours. (Distinct from duplication: that repeats one meaning in two places, scattering fragments one meaning across many.)

Sprawl is the failure mode here — a document simply too long, even when every line is live and unique. Attention thins across the excess. The cure is the ladder, not tighter sentences.

Completion criteria

Every step ends on a completion criterion — the condition that says the work is done. Two properties make it a lever, and both sharpen R5 (verify before you call it done):

• Clarity — can the agent tell done from not-done? A vague bound ("understanding reached") invites premature completion: ending early because attention slipped to being done. The visible steps still ahead supply the pull; the criterion's clarity is the resistance. Sharpen the bound first — it's local and cheap. Only if it's irreducibly fuzzy and you observe the rush, split the sequence so the later steps aren't in view. That only works across a real context boundary (a handoff, a subagent dispatch); an inline call clears nothing.
• Demand — how much it requires. "Every consumer of the change checked" forces thorough work where "check the change" does not. Demand drives legwork: the digging latent in the wording rather than written as its own step. It isn't step-bound — "every gate applied" binds a body of flat reference the same way.

The strongest criteria are both checkable and exhaustive. This is why R3 says every consumer and R2 says evidence you produced — both are demand, written into the bound.

Leading words

A leading word is a compact concept already living in the model's pretraining that the agent thinks with while running the document (atomic, evidence, Chesterton's Fence, tracer bullet). Repeated as a token, never as a sentence, it accumulates a distributed definition and anchors a whole region of behaviour in the fewest tokens — because it recruits priors the model already holds. Coining your own works if you define it clearly, but a made-up word recruits nothing: you pay in definition tokens what a pretrained word gives free. Reach for an existing word first.

It anchors twice — in the body for execution (the same behaviour every time the word appears), and in a pointer for invocation (when the same word lives in your prompts, your docs and your code, the agent links them and reaches the material more reliably).

Hunt for passages begging to collapse into one token. A triad spelled out at three sites; a pointer spending a sentence to gesture at one idea:

• "fast, deterministic, low-overhead" → tight (a tight loop).
• "a loop you believe in" → red — a fuzzy gate becomes a binary observable state.

Assume every document is carrying restatements that leading words retire. Go find them.

Negation is the failure mode beside this lever. Steering by prohibition drags the forbidden behaviour into context and makes it more available, not less — don't think of an elephant, and the elephant is all there is. The negation is a weak modifier the strongly-activated concept overruns, so the ban half-reads as an instruction. Prompt the positive: state the target behaviour so the banned one is never spoken. A prohibition earns its place only as a hard guardrail you cannot phrase positively — and even then, pair it with the positive target.