---
name: agent-doc-authoring
description: >
  Use when writing or editing any document AI agents will read — CLAUDE.md, AGENTS.md,
  specs, standards, plans, skill files (SKILL.md), subagent/system prompts. Also when a
  doc carries private codenames or nicknames, reads as prose narrative instead of
  imperatives, or needs naming/wording decisions for an agent audience. Read before
  writing the doc; check the diff against it before declaring the doc done.
---

# Authoring Documents for AI Agents

**Audience of any such doc:** a model. Optimize every token for *model activation*, not human aesthetics. Words are levers on the model's priors, not decoration. State this audience inside the doc itself ("audience: AI coding agents first") — it licenses optimizing for activation and warns future editors not to "prettify" it back into prose.

## The levers, strongest first

1. **Concrete imperative rule** — "Do X. Never Y." The strongest steer. Lead with it.
2. **Before/after example** — a model imitates a shown example more reliably than it obeys an abstract rule. Show the exact target shape; tag every anti-pattern `// reject:` or "DO NOT".
3. **Recognized principle name** — the *weakest* lever: a prior-activator, not an instruction. Use it only to switch on the right prior, never alone to carry behavior.

Lead with 1, anchor with 2, tag with 3.

## Register: caveman compression (DEFAULT for agent-facing docs)

Default writing register = **caveman**. Agent-facing doc read many times across a dev cycle → every article/filler token taxed on every read. Compress form hard.

**DROP** (zero model-activation): articles (a/an/the), filler (just/really/basically/simply/actually), pleasantries, hedging, narrative connective tissue, throat-clearing intros, restated conclusions. Fragments OK. Short synonym over long (big not extensive; fix not implement-a-solution-for).

**HARD FLOOR — NEVER caveman-compress; keep verbatim:**
- Normative keywords — MUST, MUST NOT, NEVER, ALWAYS, SHOULD. Dropping/softening one inverts the contract.
- Rule + invariant IDs and their exact statement (e.g. `R-STATS-3`, "invariant 2").
- Identifiers, paths, type names, field names, trait/function signatures.
- Code + JSON + signature blocks — unchanged (hygiene rule already forbids touching code).
- Contract clauses, gate conditions, disambiguators ("do NOT conflate X with Y").

Caveman acts on **connective prose, NEVER on the normative/actionable surface**. Terse ≠ ambiguous: cut that forces the model to guess scope or intent → keep longer form (same guardrail as `agentify-doc`). Audience-first line still required.

## Naming rules

- **Name with terms dense in training data.** Recognized principles — YAGNI, idempotency, memoization, contract-first, semantic versioning, Chesterton's Fence, "validate at the trust boundary", "tree-shakeable" — activate correct priors instantly and for few tokens.
- **Never let a private codename / internal nickname / in-joke carry meaning.** It activates nothing in the model, or mis-fires an unrelated prior (a homonym), and forces the model to reconstruct intent from nearby examples on every read. Pure context tax and a poisoning risk. If humans need a nickname, gloss it once to the real principle and never make the nickname the carrier of the rule.
- **Add-vs-restrain test — apply before using ANY pattern name.** Ask: *does this name make a model add structure or restrain it?*
  - **Restraint-principles are safe** — over-applying them just yields more restraint, which is usually the goal.
  - **Structure-producing pattern names are hazardous** (heavyweight architecture patterns, DI frameworks, precondition/postcondition contracts): a model that reads them starts emitting that structure everywhere, including where you wanted minimalism.
  - Prefer a **scoped** term ("adapter at the boundary") over a **grand unscoped** one that implies the structure belongs everywhere.

## Structure rules

- **Ladders and checklists, not prose.** Number steps; "stop at the first rung that holds." Agents follow ordered lists far more reliably than narrative.
- **State the decision rule, not its derivation.** Give the rule to apply ("≥2 consumers → build; 1 → don't"), not the essay that produced it. Rationale goes below, labeled, skimmable.
- **BLUF — rule/result first, rationale after**, in every section.
- **Scope every instruction.** Say where it applies AND where it doesn't ("inside a function" vs "at a public export"). Unscoped rules over-generalize.
- **Separate the actionable surface from the why.** Put the lists where the agent acts; keep explanation clearly secondary so it is never mistaken for an instruction.

## Hygiene rules

- **No poisoning tokens.** No ambiguous homonyms, jokey labels, or large unframed blocks of bad code — models pattern-match to whatever is present. Frame every anti-example with an explicit "DO NOT", and keep the doc's own tokens aligned with the behavior you want.
- **One source of truth — point, don't re-inline.** Duplicated doctrine drifts. Reference the canonical doc; do not copy it.

## Before declaring the doc done

- [ ] Every instruction is an imperative, scoped, and BLUF-ordered.
- [ ] No private codename/nickname carries meaning; every named pattern passed the add-vs-restrain test.
- [ ] Load-bearing examples are present and correct; anti-examples are framed "DO NOT".
- [ ] No duplicated doctrine — canonical source is pointed to, not copied.
- [ ] Audience-first line present.
- [ ] Caveman register applied to prose; HARD FLOOR (normative keywords, rule IDs, identifiers, code blocks, contract clauses) intact verbatim.

To *rewrite an existing* doc/skill into this form, use the `agentify-doc` skill — it applies these directives as a tokenomics-aware transform.