Writing for AI Agents: A Craft Reference
A theory of writing any document an agent consumes — skills, CLAUDE.md, reference docs — built on context pointers, an information hierarchy of steps versus disclosed reference, completion criteria, and leading words that anchor behavior in the fewest tokens.
A skill or CLAUDE.md that half-works isn't usually wrong — it's just badly engineered as a document: the wording of one pointer decided whether the agent ever reached the rule that mattered, and nobody was thinking about that when it got written.
Who it's for: developers writing or maintaining CLAUDE.md and AGENTS.md files, skill authors trying to make triggering reliable, teams whose agent docs have grown long and inconsistent, anyone who wants a systematic craft for writing documents an agent actually follows instead of trial-and-error prompting
Example
"My CLAUDE.md keeps missing rules and my skill barely triggers" → A diagnosis using context pointers (is the wording sharp enough to fire the branch that matters?), the information hierarchy (should this be an in-file step, in-file reference, or pushed behind a pointer?), and a pruning pass that hunts no-ops and duplication sentence by sentence — restructured, not just trimmed
CLAUDE.md Template
New here? 3-minute setup guide → | Already set up? Copy the template below.
npx ccplaybooks add writing-for-ai-agents# Writing for AI Agents — A Craft Reference
Reference for writing any document an AI agent consumes: a skill, a `CLAUDE.md`/`AGENTS.md`, a reference doc reached by a pointer. The packaging differs; the writing doesn't — the same levers make each one predictable, because the agent takes the same *process* every run rather than producing the same output a human writer would.
Use this whenever you're drafting or editing a skill, a `CLAUDE.md`, or any doc an agent is meant to follow reliably.
## Context Pointers
A **context pointer** is a reference held in the agent's context that names some out-of-context material and encodes the condition for reaching it. A skill's description is one; a line in `CLAUDE.md` naming a doc is the same object. The pointer's *wording*, not its target, decides when the agent reaches the material, and how reliably. A must-have target behind a weakly worded pointer is a variance bug: sharpen the wording first, and only inline the material if sharpening fails.
A pointer does two jobs: state what the material is, and list the **branches** that should trigger reaching it (a branch is a distinct case the document handles — different runs take different paths through it). Every word of an always-loaded pointer costs on every turn, so it earns even harder pruning than the body:
Get new playbooks like this one
One email a week with new Claude Code workflows. Free, like everything here.
No spam. Unsubscribe anytime.
What This Does
A craft reference for writing anything an agent reads and follows every run — a skill, a CLAUDE.md/AGENTS.md, a reference doc reached by a pointer. The core insight: the packaging differs, but the writing doesn't, because the agent takes the same process each time rather than producing a one-off human-readable output. That means the same handful of levers — how a pointer is worded, where material sits on the information hierarchy, how sharp a completion criterion is, whether a concept is anchored with a leading word — decide whether the document actually gets followed.
It covers context pointers (a pointer's wording decides whether it fires, not its target), the information hierarchy of in-file steps versus in-file reference versus disclosed reference, when premature completion happens and how to defend against it, leading words as a token-efficient way to anchor behavior, and a concrete pruning discipline for hunting duplication, staleness, and no-ops sentence by sentence.
Quick Start
Step 1: Create a Project Folder
mkdir writing-for-agents && cd writing-for-agents
Step 2: Download the Template
Click Download above, then:
mv ~/Downloads/CLAUDE.md ./
Step 3: Apply It to a Real Document
claude
Then paste in the skill, CLAUDE.md, or reference doc you're struggling with and ask Claude to restructure it using this framework — or ask it to draft a new one from scratch with these principles in mind.
Tips & Best Practices
- Sharpen a pointer's wording before you inline the material behind it — a must-have target behind a weakly worded pointer is a variance bug, and the cheap fix is almost always wording, not restructuring.
- When a
CLAUDE.mdhas grown long and the model seems to miss rules buried in the middle, that's the sprawl failure mode. Restructure with the information hierarchy — don't just trim words from individual sentences. - Reach for an existing word before coining your own leading word. A pretrained concept (fog of war, tracer bullet) anchors behavior for free; a made-up word costs you the definition tokens a real one gives away.
- Run the no-op test on every sentence during a pruning pass: does it change behavior versus what the model already does by default? If not, delete the whole sentence rather than trimming it.
Limitations
- This is a craft reference, not a linter — applying it well still takes judgment about where each specific piece of content belongs on the hierarchy.
- Pairs well with, but doesn't replace, a dedicated tool for restructuring an already-bloated
CLAUDE.md— this playbook is about writing and organizing from the ground up, not a mechanical two-level split. - Best suited to documents an agent reads repeatedly across many runs; a truly one-off instruction doesn't need this level of engineering.