writing-for-agents

Writing for Agents

A document a human reads and a document an agent re-reads on every invocation serve different needs, and the mismatch is where most skill docs go wrong. This skill's defining constraint adapts Diátaxis (the four-way documentation framework (tutorial, how-to, reference, explanation)) to that difference: an agent almost never needs a tutorial (a guided first-exposure experience; the agent isn't building lasting comprehension across sessions the way a human learner is), so a document written for an agent should be built almost entirely from how-to (the steps it executes) and reference (facts it consults on demand), with explanation (the "why") minimized or relocated to where a human maintainer, not the executing agent, will actually read it.

Phase 1: Classify before writing

Before adding a line, decide which Diátaxis quadrant it belongs to:

• How-to: an ordered action the agent takes. This is the spine of most skill documents.
• Reference: a fact, definition, or rule consulted on demand, not read top to bottom (a table of standards, a checklist of criteria).
• Explanation: the reasoning behind a choice, useful for understanding why, not for knowing what to do.
• Tutorial: a guided first-exposure walkthrough. Almost never belongs in an agent-facing document: see Phase 4.

Content of one kind buried inside another is where documents go stale and hard to maintain: an explanation sitting mid-procedure reads like a step, and an agent that treats it as one either stalls or improvises past it.

Phase 2: Write the how-to as the spine

The numbered phases or steps are what the agent actually executes, in order, each ending on a condition clear enough to tell done from not-done. This is the tier that earns the top of the document; everything else exists to support it, not to compete with it for attention. Write generated prose without em dashes, using a comma, colon, period, or a reworded sentence instead.

Phase 3: Push reference behind structure, not narrative