The breakout everyone's talking about
Matt Pocock's writing-for-agents skill hit 264,042 stars on SkillsMP, adding 7,682 in the last week alone. It's marked as a breakout. If you follow the agent skills ecosystem at all, you've probably seen it.
But here's the thing: this skill doesn't do anything. It doesn't lint your AGENTS.md, it doesn't auto-generate prompts, and it won't speed up your coding session. What it does is something quieter and, honestly, more important — it teaches you how to write documents that AI agents actually consume well.
That distinction matters, and it's the first thing I want to be honest about.
What this skill actually is
Reading the SKILL.md, I realized this is a meta-skill. It's not a tool for building software — it's a framework for writing the documents your agent reads before it builds software. Skills, AGENTS.md files, CLAUDE.md files, any pointer-driven reference material. If an agent consumes it, this skill has an opinion on how to write it.
The core thesis is deceptively simple: agents don't read the way humans do. They follow a process every run, not a fixed output. So the writing needs to account for how an agent actually navigates context — what it loads always, what it reaches for on demand, and what it ignores entirely.
The author calls this the "information hierarchy." Steps go at the top because the agent needs them in order. Reference sits below, consulted on demand. And behind every pointer is a trade-off between context load (tokens spent every turn) and cognitive load (the human's burden of knowing what exists).
Why this matters more than you'd think
The gap between writing for humans and writing for agents is enormous, and most of us are still writing AGENTS.md files like they're READMEs. We dump context in, hope the agent reads it, and wonder why it misses things.
This skill gives you the vocabulary to diagnose that failure. When an agent skips a section, it's not disobedience — it's a pointer problem. When it rushes through a step, it's a completion criterion problem. When it forgets a rule buried in a 200-line reference file, it's an information hierarchy problem.
That diagnostic framework alone is worth the install, even if you never restructure a single document.
What I actually took away from it
Five concepts stuck with me:
Context pointers. A pointer isn't just a link — it's a trigger. The wording decides when the agent reaches the material. A weakly-worded pointer behind a must-have target is, in the author's words, a "variance bug." Sharpen the wording before you inline more content.
Leading words. Using a compact concept the model already knows (like "tracer bullets" or "fog of war") as a recurring token anchors behavior more efficiently than inventing your own terminology. One pretrained word recruits priors for free; a coined word costs you definition tokens every time.
Completion criteria. Every step needs a condition that tells the agent it's done. Vague bounds invite premature completion. The fix is to sharpen the bound first — not to hide the remaining steps, which only works across a real context boundary.
Progressive disclosure. Push reference behind pointers so the main document stays legible. But the author is clear that this isn't token optimization — it's protecting the hierarchy. If a piece of reference is needed by every branch, it stays inline. If only some branches need it, it goes behind a pointer.
The two loads. Context load costs tokens every turn. Cognitive load costs the human their mental model. You're always spending one or the other. The skill gives you a framework for choosing which one to spend.
Who should install this
If you maintain AGENTS.md or CLAUDE.md files across multiple projects, or if you're building skills for others to use, install this. The frameworks for pointer design and completion criteria will change how you write those files immediately.
If you're a solo developer with a simple project and a two-line AGENTS.md, you probably don't need it. This skill assumes you're writing documents at a scale and complexity where these trade-offs actually bite.
If you're looking for a tool that automates anything — sorry, this is a thinking framework, not a utility.
How to install
You can add it via the Claude Code plugin (claude plugins install mattpocock-skills) or through npx skills@latest add mattpocock/skills for Codex and other agents. The SkillsMP page has the full breakdown. Once installed, you'd invoke it when you're creating or editing any document an agent consumes.
Honest concerns
The SKILL.md itself is dense. I'd describe it as a 40-page essay on information architecture applied to agent context. The concepts are sound, but the density means you'll probably need to re-read it twice before the ideas click. That's not a flaw — it's just honest about what you're getting into.
There's also a tension worth noting: the skill advocates for lean, well-structured documents, but the skill document itself is not lean. It's a deliberate teaching artifact, and the author acknowledges that some material needs to be upfront to teach the concept. Still, if you're looking for a model of the principles it describes, the document itself is a case study in where it sits on the hierarchy — heavy on reference, light on steps.
And the biggest limitation: this skill has no automated enforcement. It's principles, not guardrails. Nothing prevents you from writing a bad AGENTS.md after reading it. It just gives you better instincts.
Verdict
Install it. Not because it'll change your next coding session, but because it will change how you think about every instruction file you write afterward. The frameworks around context pointers, completion criteria, and information hierarchy are genuinely useful, and they fill a gap I didn't know existed until I read the doc.
The fact that it's trending breakout on SkillsMP with 264k stars tells me the community is recognizing that agent documentation is a real discipline — not an afterthought. This skill is one of the first to treat it as one.
Just go in expecting a conceptual read, not a productivity hack.
SkillsMP: skillsmp.com/creators/mattpocock/skills/skills-productivity-writing-for-agents GitHub: github.com/mattpocock/skills/tree/main/skills/productivity/writing-for-agents