The 8,658-star signal you're ignoring
Here's a number that should make you pause: a skill called writing-for-agents by Matt Pocock sits at 8,658 stars on SkillsMP and gained zero in the last week. That's not a trending spike — that's a slow, steady accumulation from developers who keep coming back to it. In a marketplace full of flash-in-the-pan utility skills, that kind of retention is rare and telling. It means people aren't just installing it; they're using it. Re-reading it. Referencing it mid-workflow.
So I went deep on the SKILL.md. Here's what I found.
What this skill actually is
Let me be upfront: this is not a skill that writes skills for you. If you're looking for a magic prompt that generates a polished AGENTS.md or a brand-new agent skill, this will disappoint you. Instead, writing-for-agents is a reference document — a writing framework — for anyone creating documents that agents consume. Skills, AGENTS.md files, pointer-linked docs — anything that lives in an agent's context and shapes its behavior.
Matt Pocock (the author, also known in the TypeScript community) treats agent documentation as a distinct engineering problem with its own physics. The packaging differs between a skill and an AGENTS.md, but the writing follows the same rules. And those rules are not intuitive unless you've thought carefully about how agents actually read.
Why this matters
Most of us write AGENTS.md files the same way we'd write a README for a human: descriptive, comprehensive, friendly. We dump context in there and assume the agent will parse it. But agents don't read the way humans do. They follow pointers, trigger on specific wording, and burn context budget on every token in their window — whether that token is firing or not.
The gap this skill fills is the difference between documentation that exists and documentation that an agent can actually act on. A weakly worded pointer to a must-have target is, in the author's words, a "variance bug." That framing alone is worth the install — it reframes documentation quality as a reliability issue, not a cosmetical one.
What you actually get: five capabilities that hit
1. Context pointers as a first-class concept. The skill introduces the idea that a pointer is not just a link — it's a trigger. Its wording decides when the agent reaches material and how reliably. You learn to front-load the leading word, collapse synonym branches, and cut identity the body already carries. This alone will change how you write AGENTS.md files.
2. The two-load model. Every piece of documentation spends one of two budgets: context load (always-loaded tokens costing attention every turn) or cognitive load (the human's mental index of what exists and when to reach for it). This framework forces you to ask — before writing anything — which budget you're spending, and whether that spend is justified.
3. The information hierarchy. Steps vs. reference. In-file vs. disclosed vs. external. The skill gives you a ladder to place each piece of content based on how immediately the agent needs it. Progressive disclosure isn't a token optimization — it's how you protect the hierarchy so the agent isn't wading through reference material while trying to execute a sequence.
4. Completion criteria as a lever. Every step needs a criterion that tells the agent "you're done." The skill distinguishes between clarity (can the agent tell done from not-done?) and demand (how much work does it require?). Vague bounds invite premature completion — a genuinely insidious failure mode where the agent wraps up early because the finish line was fuzzy.
5. Leading words. Compact, pretrained concepts the agent already holds in its weights — words like lesson, tracer bullets, fog of war. Used as tokens rather than sentences, they accumulate distributed definitions and anchor behavior across the entire document. This is the most technically interesting section: it's essentially a compression strategy for agent behavior, recruiting priors the model already has instead of spending tokens defining new terms from scratch.
Who should install this (and who shouldn't)
Install it if: you maintain projects with AGENTS.md files, you build custom skills for Claude Code or Codex, or you care about the reliability of agent behavior across runs. If you've ever wondered why an agent ignored a perfectly reasonable instruction buried in your documentation, this skill will diagnose why.
Don't install it if: you want a tool that generates documentation for you, or if your projects are small enough that a one-page AGENTS.md covers everything and nobody touches it. This is a framework for people who are iterating on agent documentation and hitting real friction. If you're not hitting that friction, you're paying cognitive tax for a skill you don't need yet.
Honest concerns
The biggest limitation: this is a reference document, not an interactive tool. It won't lint your AGENTS.md, won't rewrite your skill descriptions, won't flag weak pointers. You have to internalize the framework and apply it yourself. For some developers, that's fine — they'll treat it as a style guide. For others, it'll collect dust after one read.
The writing is dense. Dense in a way that rewards re-reading but punishes skim-reading. If you're expecting a quick checklist, you'll bounce off it. The concepts compound — context pointers feed into the two-load model feeds into the information hierarchy — and skipping ahead loses you the thread.
There's also the question of applicability scope. The framework assumes you're writing for a specific class of agent (one that follows pointers, respects context budgets, and triggers on wording). As agent architectures evolve, some of these assumptions may shift. But as of now, the mental model is solid and the principles are transferable across most current agent systems.
Verdict
Install it. Even if you only read it once and take away the concept of context pointers, it will change how you write agent-facing documentation. The 8,658-star count isn't hype — it's the community slowly converging on the idea that writing for agents is a distinct discipline with distinct rules, and this skill lays those rules out with unusual clarity.
It won't make your agent faster or smarter. But it will make your documentation legible to something that reads nothing like a human. In a world where agent reliability depends on how well the instructions land, that's not a small thing.
SkillsMP: skillsmp.com/creators/openchamber/openchamber/agents-skills-writing-for-agents GitHub: github.com/openchamber/openchamber/tree/main/.agents/skills/writing-for-agents
To install: drop the skill into ~/.claude/skills/writing-for-agents/ or .claude/skills/writing-for-agents/ and reference it when building or editing agent-consumable documents.