writing-for-agents is a reference for writing any document an agent reads: a Skill, an AGENTS.md or CLAUDE.md (an instruction file), or a doc the agent reaches through a pointer. The aim is that the agent takes the same process every run. Its main ideas:
Context pointer: a line in the agent's context that names material kept elsewhere and says when to reach for it. A Skill's description is one. The pointer's wording, not its target, decides when the agent reaches the material.
Two loads: context load is what always-loaded text costs the agent on every turn. Cognitive load is what it costs you to remember which documents exist and when to use each.
Information hierarchy: steps first, then reference, then reference moved into a separate file behind a pointer. Keep in the file what every case needs; move out what only some cases need.
Completion criterion: every step ends on a clear condition that tells the agent it's done.
Prompt the positive: say what to do, not what not to do. A ban puts the banned idea in the agent's head.
Pruning: say each thing in one place, don't copy what the agent can look up (like package.json scripts), and delete lines that change nothing.
When to use it
Use it when you create or edit a Skill, or change an AGENTS.md or CLAUDE.md. For example, adding a line to your FastAPI repo's CLAUDE.md that points agents at your SQL migration notes. It's model-invoked, so the agent reaches for it on its own when it writes one of these.
When not to use it
To find out what to change in the agent's setup after a build, use retro. It looks back over the session and suggests changes. writing-for-agents is how you then word them.
To sharpen your project's own words in GLOSSARY.md, use domain-modeling.
What it needs to start
A document you're writing or editing. When that document is a Skill, the agent also reads SKILL-MECHANICS.md, which covers the front matter, the choice between model-invoked and user-invoked, and router Skills.
What it creates
Nothing of its own. It's reference: it shapes the document you're writing. It creates no Issues, branches or pull requests.
Going deeper
5 min read · Going deeper not read
Why it exists
The Skill began life with another name. In v1.0.0, Matt replaced write-a-skill with writing-great-skills, "a reference for writing and editing skills well". Then, in his v1.2 video of 5 August 2026, he said why it changed:
I noticed that I was using it for stuff other than skills.
He was using it, in his words, "for anything that an agent read". So v1.2.0 renamed it writing-for-agents. The CHANGELOG marks this as Breaking, and his v1.2 post adds: "There is no alias, and the old name is gone."
The problem it solves is in its docs page (updated 24 August 2026): "Ask an agent to write instructions for another agent and it spends most of its words explaining what the model already knows." Each of those lines is a no-op. So "Its default fix is to delete, not to explain."
Matt's v1.2 post names one use of that wider scope: "pull an overloaded AGENTS.md apart into skills, which stops the front-loading."
A note on dates: the docs page says "It is this skill, renamed in v1.1." The CHANGELOG at the pin commit and the v1.2 post (5 August 2026) put the rename in v1.2.0. The docs page (updated 24 August 2026) is newer. But the CHANGELOG's 1.2.0 entry records what shipped, so this Lesson follows it.
The idea is a budget. Matt's guide to AGENTS.md (updated 18 January 2026) credits Kyle from HumanLayer with the "instruction budget". It says: "Every token in your AGENTS.md file gets loaded on every single request, regardless of whether it's relevant." Its cure is progressive disclosure: "give the agent only what it needs right now, and point it to other resources when needed." writing-for-agents applies the same idea to every document an agent reads.
Anthropic's guide to context engineering (September 2025) states the same idea in its own words. Models have an "attention budget", and "Every new token introduced depletes this budget by some amount". Its advice is to find "the smallestpossible set of high-signal tokens".
Claude Code shows the trade in its own docs. By default, the description is always in context, and the full Skill loads when invoked. With disable-model-invocation: true, the description is not in context. So a description is context load you pay every turn, in exchange for the agent being able to find the Skill.
By default
With disable-model-invocation: true
the description
is always in context
is not in context
the full Skill
loads when invoked
loads when invoked
Claude Code shows the trade in its own docs.
A real example
The Skill follows its own rules. When it was renamed, the CHANGELOG says, the Skill-only mechanics "are disclosed to a new SKILL-MECHANICS.md". Line 8 of SKILL.md is the context pointer to it: "When the document you're writing is a skill, read SKILL-MECHANICS.md".
The same release merged its old GLOSSARY.md into SKILL.md, for "one authoritative treatment per term". That is the single source of truth rule, applied to itself.
Where it goes wrong
The rename broke it in Codex. On 5 August 2026, the day v1.2.0 shipped, a user opened issue #748. Since v1.2, each Skill has a second file beside it, agents/openai.yaml, which carries its settings for Codex. The rename "moved agents/openai.yaml without updating its contents". That file still said allow_implicit_invocation: false. The fix, pull request #766, explains the result: "the skill's description could never trigger it — only a literal $writing-for-agents mention worked." So a model-invoked Skill behaved like a user-invoked one. The invocation choice lived in two files, and only one was changed. The fix merged the same day and shipped in v1.2.2.
Trimming for length cuts behaviour. Matt's docs page answers a question people ask him: "I asked an agent to trim a document and it cut the functionality." His reason: "Agents told to "streamline" optimise for length, because length is the thing they can see." The no-op test checks behaviour instead: "delete the line and ask whether the agent's behaviour changed."
A Skill built from one run fits only that run. The usual method is to do the work once, then have the agent write it up as a Skill. Matt says that "fits that one run too closely, and the examples come out too specific." His fix: "strip what belonged to that repo and those files, and write for the class of task."
Letting the agent write it alone. "Left alone the model explains what it already knows." Matt says to use the reference to review the draft: "Most of its value comes from that review pass."
Try it
In your practice project (set it up first with keeping-track's Try it step if you haven't): in a fresh session, ask the agent to review your repo's root CLAUDE.md (write one first with instruction-files' Try it step if you have none) with writing-for-agents, and list every line that is a no-op or a cache of something the agent can look up: a config file, web/package.json scripts or --help output. Delete one listed line whole, give the agent one small task, such as "add a field to the booking model", and keep the deletion only if its behaviour didn't change. Repeat for each line.
The Skill's own rule for this step: "When a sentence fails, delete the whole sentence rather than trim words from it."