Classify and structure content going into a document an agent reads (a skill, AGENTS.md, CLAUDE.md, a linked doc) so procedure, facts, and rationale don't get tangled together. Use when creating or editing a skill, or writing/editing AGENTS.md or CLAUDE.md.
Collected from public GitHub. Every version is saved exactly as it was and never changes. Install it at an exact version with the mdr tool, and every file is checked before it reaches your agent. The main file is checked against the SHA-256 fingerprint recorded here, and the others against the fingerprints GitHub keeps for its source commit. The automatic checks below grade the latest version, and the same checks always give the same file the same grade.
What the file says
# 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).
…
The line at the top of this page pins the label git:20260809.2a45dbb, which is what most people want. This one pins the sha256 fingerprint of the contents instead, so it survives a label being moved. Either way the exact version is written to mdr.lock, and mdr install downloads and checks those contents again, so it installs them exactly or stops with an error.
A 17 of 17 checks passed. Fixed automatic checks with no AI involved, so the same checks give the same answer every run.
pass: Frontmatter block present
pass: Frontmatter declares a name
pass: Frontmatter declares a description
pass: Size between 200 bytes and 200 KB (4784 bytes)
pass: No zero-width or bidi control characters
pass: No instruction hidden inside an HTML comment
pass: No link to an exfiltration or paste host
pass: No credential-shaped string
pass: No instruction to send local credentials anywhere
pass: No text hidden with inline styles
pass: No prompt-injection phrasing
pass: No curl or wget piped into a shell
pass: No recursive delete of root, home or parent
pass: No instruction to read or print local credentials
pass: No base64 blob over 200 characters
pass: No link to a raw IP address
pass: No script tag
Source
GitHub
aethrox/doctrine · 19 stars · license MIT · pushed 2026-09-11 · branch main
API
GET https://markdownregistry.com/api/v1/artifacts/art_wheznjlo3zs5ozeu
GET https://markdownregistry.com/api/v1/resolve?ref=aethrox/doctrine/writing-for-agents
GET https://markdownregistry.com/api/v1/blob/4952ee48302d03ccf4de174278d7193b29e5c71807bd9d9dd91895f7b0e62445
Your AI assistant does the legwork. You hear about the deals worth your word. Hand yours the standing instructions at modelranch.com and it joins the network that reads files like this one.
aethrox/doctrine · skills/api-design-standards/SKILL.md · API design discipline grounded in the Microsoft/Google REST guidelines, resource and URL conventions, a chosen…
aethrox/doctrine · skills/architecture-diagram/SKILL.md · Produce a software architecture diagram at the right level of zoom, using diagram as code so it can be shown inline…
aethrox/doctrine · skills/capacity-estimation/SKILL.md · Turn a vague performance requirement into arithmetic before the architecture is chosen, size concurrency with Little's…
aethrox/doctrine · skills/code-review/SKILL.md · Code review discipline: the approval bar is "improves code health," not "perfect," Fowler's code-smell catalog gives…
aethrox/doctrine · skills/code-style-lint/SKILL.md · Discipline for code style and static analysis, adopt the ecosystem's established formatter as the non-negotiable source…
aethrox/doctrine · skills/codebase-design/SKILL.md · Module design discipline from John Ousterhout's A Philosophy of Software Design, depth as the metric (a lot of…
aethrox/doctrine · skills/dependency-upgrade-management/SKILL.md · Discipline for keeping dependencies current and deprecating capabilities safely, an inventory (SBOM) of what's actually…
aethrox/doctrine · skills/diagnosing-bugs/SKILL.md · Systematic debugging discipline based on David Agans' nine rules, understand the system, reproduce reliably, bisect the…
aethrox/doctrine · skills/domain-modeling/SKILL.md · Domain-Driven Design discipline, build a ubiquitous language shared by code and conversation, draw explicit bounded…
aethrox/doctrine · skills/explain-plainly/SKILL.md · Default to explaining technical work in plain language for a non-technical audience, using an existing project glossary…
aethrox/doctrine · skills/grilling/SKILL.md · Interview the user relentlessly, in rounds, to close the gap between what's known and what's needed before acting on a…
aethrox/doctrine · skills/handoff/SKILL.md · Hand off in-progress work, an on-call shift, or an open incident to another person or agent using a fixed four-part…
kunolu/640-skills · sbtd-workflow-onboard/assets/external-skills/stable/skills/writing-for-agents/SKILL.md · Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
oyadotai/oya-browser · .agents/skills/writing-for-agents/SKILL.md · This skill should be used when creating or editing skills, agent definitions, AGENTS.md, CLAUDE.md, or reference…
oyadotai/oya-browser · .claude/skills/writing-for-agents/SKILL.md · This skill should be used when creating or editing skills, agent definitions, AGENTS.md, CLAUDE.md, or reference…
qshanx/docs-governance · skills/documentation/writing-for-agents/SKILL.md · Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
timharris707/skills · skills/author/writing-for-agents/SKILL.md · Write and prune documents an agent consumes: a SKILL.md, an AGENTS.md or CLAUDE.md, a rules file, a reference file…
timharris707/skills · plugins/clickai-codex/skills/author/writing-for-agents/SKILL.md · For skills, standing agent instructions, recorded rules, or documents agents skip, write and prune reliable triggers…
vodailocz/kilo-kit-mcp · skills/productivity/writing-for-agents/SKILL.md · Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.
