Write For Agents

---
description: "Write agent-consumed markdown well at the moment of writing. CLAUDE.md or AGENTS.md content, .claude/rules files, agent-loaded reference/context docs, navigation-pointer lines, and doc-plus-pointer extractions. Use when: 'add this to CLAUDE.md', 'write a rule for X', 'write this up for the agent', 'add a pointer to the docs', 'move this section into its own doc', 'draft an AGENTS.md section', or any drafting or editing of a markdown file an agent will load. NOT for: creating or editing a SKILL.md (playbooks:skill-authoring and skill-quality:check own that), auditing existing docs (the docs-hygiene audit skills own that), or human-facing docs such as end-user READMEs, RFCs, release notes and changelogs. Those route to docs-hygiene:write-for-humans, the sibling that fires at the same moment for the other reader."
argument-hint: "[<file or section being written>]"
user-invocable: true
disable-model-invocation: false
metadata:
  workflow-stage: anytime
  summary: Authoring-time doctrine for agent-consumed markdown
---

# 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`](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.

## 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](https://github.com/melodic-software/claude-code-plugins/blob/main/docs/conventions/invocation-mode/README.md)
(§ 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.