Write For Agents

Write For Agents

Why this skill exists

The docs-hygiene siblings are audit-shaped: they find problems in docs that already exist. This skill is the write-side complement. It fires while the doc is being written, so the problems the audits catch are not created in the first place. Its scope is any markdown an agent will consume; the auto-read surfaces (CLAUDE.md scopes, .claude/rules, auto-memory, and their kin) are the high-value core because their cost recurs every session. Read reference/agent-doc-surfaces.md when you need to know whether, when, and how much of a target file the harness actually loads. Write differently for an always-loaded surface than for an on-demand one.

Budget both loads

Every line you write spends two budgets, and cutting one can overspend the other:

• Context load. Tokens the agent pays, every session for always-loaded surfaces. Governed marketplace-wide by PLUGIN-PHILOSOPHY's Instruction economy: an instruction earns its place with observed-stumble evidence, or it goes.
• Cognitive load. Attention the human maintainer pays. The human is the index of the doc set: they must be able to hold where things live. Ten tiny fragment files can be cheaper for the agent and ruinous for the human; one 500-line file the reverse. When the two budgets conflict, say which one you spent and why.

Fewer words spends less of both, and the brevity rules that are universal apply here too: no more words than the meaning needs, no filler, hedging, intensifiers, expletive openings, or restatement of an adjacent line; active voice; one idea per sentence; a factual register with nothing sold. /writing:be-concise owns those rules when the writing plugin is installed; without it, apply them from this paragraph. Take those rules and no more of that doctrine: its human-only rules do not transfer. A bottom-line-first opening, headings written to be skimmed, bullet lists for scanning, and bounded bold all serve a person moving down a page fast, and an agent reading a rule needs the rule stated where it applies, not staged for a skim.

Write pointers that cover their branches

A pointer is a routing instruction; the reader decides whether to follow it from the pointer text alone, without opening the target.

• Front-load the leading word. Open with the term the reader is matching on ("Deploys: see…", never "See the following doc for information about deploys").
• Cover the branches. State when to follow it AND what the reader gets ("for tracked-changes output specifically, read X"), so both the follow and the skip are informed decisions.
• A pointer that exists only because changes must be mirrored across distant folders can mask a cohesion problem. Before adding it, consider restructuring so the things that change together live together, a pointer papering over low cohesion outlives the reorganization that would have removed it. (Audit-side remediation home: claude-memory:audit's C5 fix guidance, if that plugin is installed.)

The full pointer-quality criteria are owned by the sibling audit skill. Invoke /docs-hygiene:audit-progressive-disclosure via the Skill tool to grade a draft against them, rather than failing them at audit time.

Separate steps from reference, and co-locate what runs together

Steps are read in order and executed; reference is jumped into and queried. Mixing them makes both worse, a procedure interrupted by lookup tables loses its thread, and reference buried in a procedure is unfindable.

• Put the procedure in one contiguous block; move lookup material below it or into a spoke file with a conditioned pointer.
• Co-locate what is consumed together: the fact a step depends on belongs beside the step, not three sections away. Distance a reader must jump during execution is a defect.
• Sprawl is the failure of both: when a file serves several audiences or moments, split it along who-reads-when lines, not topic lines.

Give every step a completion criterion

A step is done when its criterion says so, not when text resembling the step has been produced.

• Clarity and demand. State what "done" observably is, and demand it: "run X; the step is complete when Y appears" beats "run X".
• Premature completion is the shape to design against: a step satisfiable before its goal-state is reached will be marked complete at first plausible output. Make the criterion the goal-state, never the attempt.
• Post-completion steps. When finishing creates an obligation (regenerate, notify, clean up), state it in the step, an obligation after "done" is otherwise dropped.
• The agent does the legwork. Write steps that resolve their own facts from the environment; a step that sends the human to look something up the agent could read is a defect.

Split by sequence; choose invocation by the rubric

When one doc serves two moments in time, split it at the moment boundary, the reader at step one should not scroll past material for step nine. Splitting an instruction surface into skills with different invocation modes is a different axis with its own decision rubric: follow the invocation-mode rubric (§ Splitting by invocation) rather than deciding it ad hoc.

Prompt the positive

Write what to do, not what to avoid: a prohibition drags the banned behavior into context, and pretrained leading words are the compact anchors that steer ("Prefer X" over "Never do Y unless"). Keep a negation only when the positive form genuinely loses the constraint, then pair it with the positive alternative in the same sentence.

After writing

• Repeated the same prose in another file. Even a second occurrence, or a recap of an SSOT that already exists? Invoke /docs-hygiene:extract-ssot via the Skill tool. Creating a new shared home still waits for the third occurrence; below that it remedies the repetition in place.
• Resolved or coined a term in the consuming project's domain? Invoke /domain-driven-design:curate-language via the Skill tool (if that plugin is installed) rather than hand-writing the entry. A skill defining its own working vocabulary is out of that skill's scope and stays where it is.
• Editing exposed pre-existing problems in the surrounding doc? Invoke the fitting audit sibling via the Skill tool (/docs-hygiene:audit-noise, /docs-hygiene:audit-derivability, /docs-hygiene:audit-progressive-disclosure) rather than expanding this write into an audit.

What this skill does NOT do

• Does not author skills. Deciding a skill should exist, what it triggers on, what its frontmatter declares, how its actions are shaped, and how its body is structured is playbooks:skill-authoring + skill-quality:check territory. Prose inside an already-authored SKILL.md is still this skill's: a SKILL.md is agent-consumed markdown, which is exactly and only what this doctrine governs. Read the boundary as authorship against wording, not as a whole file this skill may not look at, or the largest agent-facing surface most repos have ends up governed by no authoring doctrine at all.
• Does not audit existing docs, the audit siblings own read-only findings; this skill fires at the writing moment only.
• Does not write human-facing docs. End-user READMEs, changelogs, and marketing prose have a different reader and different rules. Those are the sibling docs-hygiene:write-for-humans, which fires at this same moment and resolves the consuming project's own style guide first.
• Does not enforce via hooks. Trigger reliability is carried by this skill's description and its eval suite, deliberately not by a forcing hook.