Write agent documents — skills, AGENTS.md, anything an agent reads — so the user can read them in one pass. A document clear to the user is clear to the agent. Be concrete about the outcome and leave the method to the agent: it thinks well, and a narrow rule makes it follow the letter and skip what you hoped it would notice. For skill frontmatter, read SKILL-MECHANICS.md.

Shape.

The first paragraph says what the document does in total.
Then short paragraphs, each led by a bold label and doing one job.
One default path per decision; name the exception only where one exists.
Each rule once. Give the reason inline where it helps the agent handle cases you didn't list.
One template in a code block for any output; one BAD/GOOD pair if a rule is subtle.
Put detail that only some cases need in a separate file, and link to it.
Number ordered steps 1, 2, 3, so steps can be referenced by number.
End each step on a clear "Done when…".

writing-for-agents