writing-for-agents

Writing for agents

Contract

Inputs

Must be supplied: the target document path and the agent-consumed document type (skill, AGENTS.md, CLAUDE.md, or pointer-reached doc). Optionally: the current document content; if absent, read it before editing.

Procedure

1. Read the target document fully. Identify whether it contains steps (ordered actions), reference (definitions, rules, facts), or both. Done when: the document is read and its content type (steps, reference, or both) is identified.
2. Apply the information hierarchy: rank material by how immediately the agent needs it:
   • In-file step: the primary tier, what the agent does, in order.
   • In-file reference: consulted on demand. A flat peer-set of rules on one rung is fine.
   • Disclosed reference: pushed to a separate file, reached by a context pointer, loaded only when the pointer fires. Done when: every piece of material is placed on the hierarchy.
3. For each context pointer (a reference naming out-of-context material with a trigger condition):
   • Front-load the leading word: the pointer's wording decides when the agent reaches the material.
   • One trigger per branch. Collapse synonyms that rename a single branch.
   • Cut identity the body already carries. Done when: every context pointer has a front-loaded leading word, one trigger per branch, and no redundant identity.
4. For each step, verify the completion criterion is both checkable and exhaustive. A vague bound invites premature completion. Sharpen the bound first; only if irreducibly fuzzy and the rush is observed, hide later steps by splitting across a real context boundary. Done when: every step has a checkable and exhaustive completion criterion.
5. Apply progressive disclosure: inline what every branch needs; push behind a pointer what only some branches reach. Keep a concept's definition, rules, and caveats under one heading (co-location), not scattered. Done when: branch-specific material is behind pointers and co-located concepts share one heading.
6. Hunt leading words: compact concepts from pretraining that anchor behaviour in few tokens. Refactor restatements into single tokens. Avoid negation: prompt the positive target so the banned behaviour is never spoken. Done when: restatements are collapsed into leading words and negation is replaced with positive targets.
7. Prune:
   • Keep each meaning in a single source of truth; duplication costs maintenance and tokens.
   • Cache only what the agent cannot find by looking. Leave one-file, one-command lookups to the environment.
   • Check every line for relevance. A line is irrelevant if it does not bear on the task or has gone stale.
   • Hunt no-ops sentence by sentence. If an instruction does not change the model's default behavior, delete the whole sentence. Done when: each meaning has one source of truth, no no-op sentences remain, and every line bears on the task.
8. For skill documents specifically:
   • Choose invocation: model-invoked (omit disable-model-invocation, write a model-facing description with trigger branches) or user-invoked (set disable-model-invocation: true, description becomes human-facing summary). Pick model-invocation only when the agent must reach the skill on its own or another skill must.
   • Split by invocation when a distinct leading word should trigger independently; pay context load only if that independent reach is worth it.
   • Split by sequence when post-completion steps tempt the agent to rush the one in front of it. Done when: the invocation mode is chosen and any split decisions are made with their trade-off justified.
9. Verify the final document is self-contained: it restates every safety, authority, execution, and proof rule the workflow needs. It contains no pointer to AGENTS.md, a system prompt, a rule file, another skill, or an optional peer step. Done when: the document is self-contained with no external runtime pointers.