Guide · Agent skill
How to use the Writing for Agents agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The writing-for-agents skill gives a coding agent a set of writing principles to follow when it writes or edits a skill, an AGENTS.md file or a CLAUDE.md file. It is for developers and teams who author instructions that other agents will read. After this guide you will know how to install the skill, how to ask for it with natural requests, and what it does and does not do.
Writing for Agentsmattpocock/skills · MIT Download the skill Quick start
- 1Download the ZIP. Get the writing-for-agents ZIP from the directory page.
- 2Unzip the skill. Unzip the folder into ~/.claude/skills/ for personal use, or into .claude/skills/ inside a project.
- 3Or upload in the Claude apps. In the Claude apps, go to Settings → Capabilities → Skills and upload the skill.
- 4Make a natural request. Ask for help writing or editing a skill, AGENTS.md or CLAUDE.md.
- 5Review the draft. Check the agent's output against your project's conventions before you use it.
What the skill makes the agent do
The skill is a reference for writing any document an agent consumes: a skill, an AGENTS.md or CLAUDE.md file, or a document reached by a pointer. Its guidance covers how to word the short descriptions that decide when an agent loads a document, how to split long material into separate files, and how to phrase steps so the agent knows when a task is actually finished.
It is text guidance only. It is a guide for writing instructions for other agents, not a tool that does work on its own.
- Write skill descriptions and pointers so the agent reaches the right material at the right time.
- Choose between keeping material in the main file and splitting it into separate files.
- Give each step a clear completion criterion so the agent can tell when it is done.
Install the writing-for-agents skill
Download the ZIP for the skill from the directory page and unzip it. The skill folder contains SKILL.md, SKILL-MECHANICS.md and agents/openai.yaml.
For a personal install, unzip it into ~/.claude/skills/. For a single project, unzip it into the project's .claude/skills/ folder.
You can also upload the skill in the Claude apps under Settings → Capabilities → Skills.
- Personal: ~/.claude/skills/
- Project: .claude/skills/ inside your project
- Claude apps: Settings → Capabilities → Skills
Trigger the skill with natural requests
The skill's description says to use it when creating or editing skills, or modifying AGENTS.md or CLAUDE.md. You can therefore ask for it in plain language that names one of those documents. You can also name the skill directly.
Requests that match the description are the most likely to load the skill.
- "Write a SKILL.md for a skill that reviews pull request descriptions."
- "Edit our AGENTS.md so the agent knows when to run the test suite."
- "Update CLAUDE.md with clearer instructions for the release process."
- "Use the writing-for-agents skill to tighten the description in this skill."
Examples of what the agent produces
When the skill is active, the agent applies its principles while drafting. For a skill, it keeps the description short and specific so the agent knows when to load it. For a long AGENTS.md, it can move detailed reference into separate files and leave a pointer that names the material and the condition for reaching it.
For steps, it aims for completion criteria that are both checkable and exhaustive, such as "every modified model accounted for" rather than "produce a change list". Review the output the same way you would review any instructions: the skill shapes the writing, but you decide whether it fits your project.
What it needs and safety notes
The skill requires nothing listed. It does not run scripts and does not use the network, so installing it adds text files for the agent to read and no executable code.
Because it is text guidance, it will not run your code or fetch information for you. Its principles are abstract, so the agent may still need judgement to apply them to your project.
- Requires: nothing listed
- Runs scripts: no
- Uses network: no
Tips for getting consistent results
Use the skill when you are writing agent documents, not when you only want to ask an agent a general question or use an existing skill. It matters only when you author these files.
Keep one trigger word per distinct case in your pointers, and reuse the same terms across your prompts and docs so the agent links them.
- Use it for SKILL.md files, AGENTS.md and CLAUDE.md, not for everyday questions.
- Check the output against your own project conventions before committing it.
- Repeat the same key terms across your documents so agents connect them.
What people use it for
- Writing a new SKILL.md with a description that loads at the right time.
- Restructuring a long AGENTS.md by moving reference material into separate files.
- Rewriting CLAUDE.md steps so each one has a clear finish condition.
- Tightening the description of an existing skill so it triggers reliably.
Frequently asked questions
Is the writing-for-agents skill free?
The skill is licensed under MIT. The source does not list any price, so check the directory page for current terms.
What does the writing-for-agents skill require?
The listed requirements are nothing. It does not run scripts and does not use the network.
Where do I install the writing-for-agents skill?
Unzip it into ~/.claude/skills/ for personal use or into .claude/skills/ in a project. You can also upload it in the Claude apps under Settings → Capabilities → Skills.
Why won't my agent use the writing-for-agents skill?
The skill loads based on its description, so ask with a request that names a skill, AGENTS.md or CLAUDE.md. You can also name the skill directly in your request.
Does the skill run code or fetch information?
No. It is text guidance only and is not a tool that does work on its own.
Is it useful if I only use existing skills?
Not really. It is meant for people writing agent documents, not for people who only want to use an existing skill or ask a general question.
New agent skills, repos and AI tools — every week
The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.
Our verdict
Use this skill if you write SKILL.md files, or maintain AGENTS.md or CLAUDE.md files for coding agents and want their behaviour to stay consistent across runs. Skip it if you only use existing skills or ask general questions, because it only matters when you author agent documents. Expect principles that still need your judgement to apply.
Download the skill