---
name: writing-for-agents
description: Use when creating or editing a skill, CLAUDE.md, AGENTS.md, or any document an agent reads through a pointer; also when a skill fires unreliably, gets skipped mid-run, or has grown too long to trust.
---

# Writing for Agents

The reference for any document an agent consumes: a skill, a `CLAUDE.md`, a doc reached by a
pointer. The packaging differs; the writing does not. The same levers make each one predictable,
because the agent takes the same *process* every run rather than producing the same output.

When the document is a skill, read [SKILL-MECHANICS.md](SKILL-MECHANICS.md) for frontmatter,
invocation, and routers.

## Start from the failure

Name the failure you are fixing before writing a line. The form that fixes one kind measurably
backfires on another.

| Baseline failure | Form that fixes it | Form that backfires |
|---|---|---|
| Knows the rule, skips it under pressure | Prohibition + rationalization table + red flags | Soft guidance ("prefer", "consider") |
| Complies, but the output is the wrong shape (bloated, buried verdict, restated spec) | Positive recipe: state what the output **is**, its parts, in order | Prohibition list ("don't restate", "never narrate") |
| Omits a required element from something it already produces | Structural: a REQUIRED slot in the template it fills in | Prose reminders near the template |
| Behavior should depend on a condition | Conditional on an observable predicate ("if the brief exists, reference it") | Unconditional rule plus exemption clauses |

Under a competing incentive, an agent negotiates with "don't X". A recipe leaves nothing to
negotiate: the output matches the stated shape or it does not.

Two rules bind whichever form you pick:

- **No nuance clauses.** "Don't X unless it matters" reopens the negotiation. Express a real
  exception as its own conditional on an observable predicate.
- **Exemption clauses do not scope.** "This limit does not apply to code blocks" still suppresses
  code blocks. If part of the output must be exempt, restructure so the rule cannot reach it.

## Prompt the positive

Negation is the failure mode beside every lever here. Steering by prohibition drags the forbidden
behavior 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 to do the thing.

State the target behavior instead, so the banned one is never spoken. A prohibition earns its place
only in row one of the table above, a discipline failure you cannot phrase positively, and even
there it pairs with the positive target so attention lands on what to do.

## 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: *tight*, *red*, *seam*, *tracer bullet*, *fog of war*.
Repeated as a token, never as a sentence, it accumulates a distributed definition and anchors a
whole region of behavior in the fewest tokens, by recruiting priors the model already holds.

It anchors twice. In the body, *execution*: the agent reaches for the same behavior every time the
word appears. In a pointer, *invocation*: when the same word lives in your prompts, your docs, and
your codebase, the agent links that shared language to the material and reaches it more reliably.

Coining your own works if you define it clearly, but a made-up word recruits no priors: you pay in
definition tokens what a pretrained word gives free. Reach for an existing word first.

Hunt for the refactor. A triad spelled out at three sites, or a pointer spending a sentence to
gesture at one idea, is a passage begging to collapse into a single token:

- "fast, deterministic, low-overhead" becomes *tight* (a *tight* loop).
- "a loop you believe in" becomes *red*, turning a fuzzy gate into a binary observable state.

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

## Context pointers

A **context pointer** is a reference held in the agent's context that names some out-of-context
material and encodes the condition for reaching 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 when
the agent reaches the material, and how reliably. A must-have target behind a weakly worded pointer
is a variance bug: sharpen the wording first, and inline the material only if sharpening fails.

A pointer does two jobs: name what the material is, and list the **branches** that should trigger
reaching it (a branch is a distinct case the document handles, so different runs take different
paths through it). Every word of an always-loaded pointer costs on every turn, so it earns harder
pruning than the body:

- **Front-load the leading word.** The pointer is where it does its triggering work.
- **One trigger per branch.** Synonyms that rename a single branch are one branch written twice.
- **Cut identity the body already carries.**
- **Name the material, never its process.** A pointer that summarizes the workflow becomes a
  shortcut the agent takes *instead of* reading the body: a description saying "review between
  tasks" produced one review where the body specified two. Name what the document covers and when
  to reach it; let the body own the steps.

## The two loads

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

- **Context load** is the cost of always-loaded material on the agent's window: a `CLAUDE.md` line,
  a skill description, anything sitting in context every turn, spending tokens and attention whether
  or not it fires.
- **Cognitive load** is the cost on you: which documents exist and when to reach for each. You are
  the index. Not a cost to minimize; it is the price of your own agency. Spend it where your
  judgment matters, remove it where it does not.

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

## Information hierarchy

A document is built from two content types: **steps** (the ordered actions the agent performs) and
**reference** (definitions, rules, facts consulted on demand). The two mix freely: all steps, all
reference, or both. The core decision is where each piece sits on the ladder, ranked by how
immediately the agent needs it:

1. **In-file step**: the primary tier, what the agent does, in order.
2. **In-file reference**: consulted on demand. Often a legitimately flat peer-set (every rule of a
   review on one rung), which is a fine arrangement, not a smell.
3. **Disclosed reference**: pushed into a separate file behind a pointer, loaded only when the
   pointer fires.

Push too little down and the top bloats; push too much and you hide material the agent needs. That
tension is the whole decision.

**Progressive disclosure** is the move down the ladder so the top stays legible. Not primarily a
token optimization: it is how the hierarchy is protected. **Branching is the test**: inline what
every branch needs, and disclose what only some branches reach. In a document with steps, in-file
reference that should be disclosed buries them and turns attending to them into a coin-flip.

**Co-location** is the within-file companion. The ladder decides how far down a piece sits;
co-location decides what sits beside it once there. Keep a concept's definition, rules, and caveats
under one heading rather than scattered, so reading one part brings its neighbors with it. The test:
the document should read like documentation written for the agent.

**Sprawl** is the failure mode here: a document simply too long, even when every line is live and
unique. Attention thins across the excess, and every extra line is one more to keep relevant. The
cure is the ladder.

## Completion criteria

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

- **Clarity**: can the agent tell done from not-done? A vague bound ("understanding reached")
  invites **premature completion**, ending the step before it is genuinely done, attention slipping
  to *being done*. The visible steps still ahead supply the pull; the criterion's clarity is the
  resistance. Defend in order: sharpen the bound first, since that is local and cheap; only if it is
  irreducibly fuzzy *and* you observe the rush, split the sequence to hide the later steps. Hiding
  works only across a real context boundary, a handoff or a subagent dispatch. An inline call leaves
  the later steps in context and clears nothing.
- **Demand**: how much it requires. "Every modified model accounted for" forces thorough work where
  "produce a change list" does not. Demand drives the digging the agent does within the work, and it
  is not step-bound: "every rule applied" binds a body of flat reference just as "every step done"
  binds a sequence.

The strongest criteria are both checkable and exhaustive.

## When to split

Splitting one document into two spends one of the two loads, so split only when the cut earns it:

- **By branch**: the disclosure test above. The most common correct cut.
- **By sequence**: split a run of steps where the later steps tempt the agent to rush the one in
  front of it. Beware the reverse: merging sequences exposes each step to what follows, inviting
  premature completion.
- **By invocation**: skill-specific, see [SKILL-MECHANICS.md](SKILL-MECHANICS.md).

## Pruning

- **Single source of truth.** One authoritative place per meaning, so changing the behavior is a
  one-place edit. **Duplication** costs maintenance and tokens, and inflates a meaning's prominence
  on the ladder past its real rank. It is the accidental inverse of a leading word, which repeats a
  token on purpose, never the meaning.
- **The environment is a source of truth too.** `package.json` scripts, config files, the directory
  layout, `--help` output. A document that restates it is a **cache**: a copy of a lookup, earning
  its load only when the lookup is expensive. Cache what the agent cannot find by looking, such as
  the unwritten convention, the reason behind a choice, the gotcha no config confesses. Leave the
  one-command lookups to the environment, where they cannot go stale.
- **Relevance.** Does the line still bear on what the document does? A line loses relevance by never
  bearing on the task, or by going stale as the world it describes changes. Without a pruning
  discipline the default fate is **sediment**: stale layers that settle because adding feels safe
  and removing feels risky, until you must core down through them to find what is still live.
- **No-ops.** An instruction the model already obeys by default pays load to say nothing. The test
  (does it change behavior versus the default?) is model-relative, not reader-relative: two people
  disagreeing about a no-op disagree about the default, and settle it by running the document, not
  by debate. When a sentence fails, delete the whole sentence rather than trim words from it. The
  test also grades leading words: a word too weak to beat the default (*be thorough*, when the agent
  is already thorough-ish) is a no-op, and the fix is a stronger word (*relentless*), not a
  different technique.

## House conventions

- **One excellent example beats five mediocre ones.** Write it in the language the document actually
  targets: TypeScript for application work, shell for infra. A complete, runnable, commented example
  from a real scenario, not a fill-in-the-blank template.
- **Name for what it does**, verb-first. Gerunds suit processes: `writing-for-agents`,
  `diagnosing-bugs`. Not `agent-doc-guidelines`.
- **No narrative.** "In the session where we found the Convex race condition" is not reusable. State
  the technique.
- **Keep the document in sync with what it describes.** A document naming a script, flag, or path
  owes the same upkeep as the code it names. A stale pointer is worse than no pointer, because the
  agent follows it.
- **Supporting files only for a reusable tool or heavy reference.** A script, a template, or a
  branch too large to inline. Principles and short patterns stay in the main file.

## Verifying

Scale the check to what the document does. Reference gets read back; discipline gets tested.

| The document is | Verify by |
|---|---|
| Pure reference (a vocabulary, an API guide) | Reading it back against the ladder and the pruning rules |
| A procedure you run yourself | Running it once on a real task; where it stalls is the bug |
| Behavior-shaping guidance: a rule expected to hold under pressure, or wording meant to change output shape | Baselining it first. Read [VERIFYING.md](VERIFYING.md) |

## Done when

- The failure being fixed is named, and the form matches its row in the table.
- Every rule is phrased as a positive target, except a discipline prohibition that cannot be.
- Each branch is inlined or disclosed on purpose, and the pointer to each disclosed file names its
  material and its trigger.
- Every step carries a completion criterion that is checkable and exhaustive.
- No line restates the environment, duplicates a meaning, or fails the no-op test.
- The document is shorter than the material it replaced.