Writing for Agents (ex Write a Skill)
The reference for writing any document an agent consumes: a skill, an AGENTS.md or CLAUDE.md, a doc reached by a pointer. Its thesis: the packaging differs, the writing does not, and the goal is the agent taking the same process every run, not producing the same output. It names the levers. The context pointer, whose wording and not whose target decides when the agent reaches the material. The two budgets, context load on the window and cognitive load on the human. The three-rung information hierarchy, in-file step, in-file reference, disclosed reference behind a pointer. And each step's completion criterion, judged on clarity (can done be told from not-done) and on demand.
Strengths
- Treats a skill's description as the real triggering lever, with concrete wording rules
- Separates context load from cognitive load, and says which one to cut and which one to accept
- A three-rung information hierarchy with a branching test to decide what gets pushed behind a pointer
- Names the failure modes (premature completion, sprawl, negation, negative space) with their cure, not just their symptom
Limitations
- Dense and abstract: reading it takes real effort, and it is no ten-minute checklist
- Matt Pocock's own vocabulary, which does not line up with Anthropic's official skills documentation
- Already renamed twice (write-a-skill, then writing-great-skills, then this): external links break fast
Best for
- Skill authors whose skills never fire on their own
- Teams maintaining a CLAUDE.md or AGENTS.md grown too long to be followed
- Agent-first repos where two runs of the same instruction do not follow the same process