Writing for Agents Skill (mattpocock): Write Better Skills

A writing guide Claude reads when you create or edit a skill, AGENTS.md or CLAUDE.md, so the document behaves the same every run.

Installs: 504.2K; on skills.sh
Stars: 309.2K; on GitHub
Files: 2; besides SKILL.md
Updated: Nov 2026; last repo commit

writing-for-agents is a reference, not a workflow. It loads when you create or edit a skill or change AGENTS.md or CLAUDE.md, and it gives Claude one set of rules for any document an agent reads: how to word pointers, where to put detail, when to split a document and what to cut.

Its core ideas are context pointers (the wording that decides when the agent reaches other material), context load versus cognitive load, an information hierarchy with progressive disclosure, clear completion criteria on steps, leading words, and pruning. A second file, SKILL-MECHANICS.md, covers frontmatter, choosing model-invoked or user-invoked skills, and router skills.

Good for

People writing their own Claude Code or Codex skills
Developers maintaining a CLAUDE.md or AGENTS.md
Teams that want agent instructions that give the same behavior each run

Install writing-for-agents

Claude Code

Copy this prompt.

Install the writing-for-agents skill in Claude Code. Run this command:

npx skills add https://github.com/mattpocock/skills --skill writing-for-agents

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Requires Node.js.

From its listing on skills.sh. Source.

What's in the skill

When it loads

Writing documents for agents. Use when creating or editing skills, or modifying AGENTS.md or CLAUDE.md.

Sections in SKILL.md

Context pointers
The two loads
Information hierarchy
Steps and completion criteria
When to split
Leading words
Pruning

Key facts

Author: Matt Pocock (mattpocock/skills)
Installs on skills.sh: 504,228 (Nov 2, 2026)
GitHub stars: 309,237 on mattpocock/skills (Nov 2, 2026)
License: MIT
Last repo commit: Nov 1, 2026
What installs: SKILL.md plus 2 bundled files: SKILL-MECHANICS.md, agents/openai.yaml
skills.sh audits: Gen Agent Trust Hub: pass, Socket: pass, Snyk: pass
Starts: When creating or editing skills, or modifying AGENTS.md or CLAUDE.md
Includes: SKILL-MECHANICS.md for skill frontmatter, invocation choice and router skills

What it includes

Wording that tells the agent when to reach other material
The pointer wording, not its target, decides when the material is reached. One trigger per branch.
Context pointers
Context load (agent window) versus cognitive load (the human)
Every document you add spends one of these two budgets.
The two loads
Steps first, reference next, disclosed reference last
Progressive disclosure moves detail behind pointers so the top stays readable.
Information hierarchy
Each step ends on a clear done condition
A vague bound invites the agent to finish early.
Steps and completion criteria
Split a document by sequence or by invocation
Splitting spends one of the two loads, so it must earn the cut.
When to split
Use compact words the model already knows
Words like "red" or "tight" retire long restatements. Prefer positive instructions to prohibitions.
Leading words
Keep one source of truth and cut stale lines
Do not restate what the environment already shows, such as package.json scripts.
Pruning
Frontmatter, model- or user-invoked skills, router skills
Set disable-model-invocation: true for skills only a human should start.
SKILL-MECHANICS.md

From the official docs

Questions

What does writing-for-agents do?

It gives Claude a set of rules for writing documents that agents read: skills, AGENTS.md, CLAUDE.md and docs reached by a pointer. It focuses on making the agent take the same process every run.

How do I install it?

Follow the install box at the top of the page.

When does it load?

When you create or edit a skill, or change AGENTS.md or CLAUDE.md. Its description names those cases.

What is a context pointer?

A reference in the agent's context that names material outside it and says when to reach it. A skill description is one, and so is a line in AGENTS.md that names a doc.

What is progressive disclosure?

Moving detail out of the main file and behind a pointer, so the top stays short. Inline what every branch needs and push out what only some branches reach.

Does it run scripts or need an API key?

No script or key is named in SKILL.md. It bundles SKILL-MECHANICS.md and a Codex metadata file.

Information

updated Nov 2, 2026

Repository: mattpocock/skills
Folder: skills/productivity/writing-for-agents

mattpocock/skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 3

writing-for-agents SKILL.md · github.com
skills.sh listing · skills.sh
SKILL-MECHANICS.md · github.com