Skip to content
Get packs

Writing for Agents

Guides writing skills, AGENTS.md and CLAUDE.md files so agents follow them reliably.

Source Download skill
Repository
mattpocock/skills
Stars
309,658
Licence
MIT
Files
3 files

What it does

When you ask an agent to write or edit a skill, an AGENTS.md file or a CLAUDE.md file, this skill gives it a set of writing principles to follow. It 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 a guide for writing instructions for other agents, not a tool that does work on its own.

Great for

  • Developers writing SKILL.md files or agent instruction documents
  • Teams maintaining AGENTS.md or CLAUDE.md files for coding agents
  • People who want their agent instructions to behave consistently across runs

Skip it if

  • People who just want to use an existing skill or ask an agent a general question, since it only matters when authoring agent documents
  • Anyone expecting it to run code or fetch information, since it is text guidance only; the principles are abstract and may need judgement to apply

Try asking

  • “Help me write a SKILL.md for a skill that drafts release notes.”
  • “Review my CLAUDE.md and tell me which sections should move into separate files.”
  • “Sharpen the description line for this skill so the agent loads it only when needed.”
  • “Rewrite the completion criteria in this workflow so they are clear and checkable.”
Step-by-step guide: how to use Writing for AgentsInstall, first run, examples, tips and FAQs

Install in 3 steps

  1. 1

    Download the skill

    The ZIP contains the 3 original files, the MIT licence and an attribution note.

    writing-for-agents.zip
  2. 2

    Add it to your agent

    Claude Code (all projects)

    mkdir -p ~/.claude/skills && unzip writing-for-agents.zip -d ~/.claude/skills/

    Claude Code / Agent SDK (this project only)

    mkdir -p .claude/skills && unzip writing-for-agents.zip -d .claude/skills/

    Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.

  3. 3

    Ask for the task

    No special command needed — the agent reads the skill's description and loads it when your request matches. Try one of the prompts above.

Get better results

  • Point it at the specific file you are writing so the guidance is applied to real content.
  • Read SKILL-MECHANICS.md alongside it when writing a skill, since frontmatter and invocation rules are described there.
  • Treat its advice as a starting point and test the resulting document by running the agent on several examples.

What's inside

  • agents/openai.yaml
  • SKILL-MECHANICS.md
  • SKILL.md

Redistributed unmodified from mattpocock/skills under the MIT licence. The assessment was drafted with AI from the skill's files on 2026-10-29. Skills can instruct your agent to run code — read SKILL.md and any scripts before installing.