How to use the writing-skills agent skill: create and test SKILL.md files

What does the writing-skills skill make the agent do?

When you ask the agent to create, edit or validate a skill, this skill tells it to treat documentation like code under test. The core rule in the source is that if you have not observed the agent failing without the skill, you do not know whether the skill teaches the right thing.

It also gives guidance on writing good skill descriptions (the trigger text that tells the agent when to load the skill), keeping documents short, naming skills with active verb-first names, organising files, and deciding when a skill should not be created at all. One example from the source: a one-off fix or project-specific convention belongs in a project CLAUDE.md file, not in a skill.

• Write baseline test scenarios and run them with subagents before writing the skill
• Write the SKILL.md, then confirm the agent now follows the rules
• Refactor: close the loopholes the agent found under pressure
• Keep descriptions to trigger conditions only, starting with "Use when..."
• Keep frequently loaded skills short (the source suggests under 200 words in total)

How do you install the writing-skills skill?

You can install it in one of two ways. For a personal install, download the ZIP from this page and unzip it into ~/.claude/skills/. To limit it to one project, unzip it into the project's .claude/skills/ folder instead.

In the Claude apps you can instead upload the ZIP under Settings → Capabilities → Skills.

• Personal: unzip into ~/.claude/skills/
• Single project: unzip into .claude/skills/ inside the project
• Claude apps: Settings → Capabilities → Skills, then upload the ZIP

How do you trigger the skill with a natural request?

You do not need a special command. Describe the task in plain language, and the agent will load the skill when the request matches its description. The description of this skill covers creating new skills, editing existing skills, and validating a skill before deployment.

Be specific about the skill you are working on. Mention the file or folder if you have one, and say whether you are creating something new or changing something that already exists.

• "Help me write a new SKILL.md for a skill that formats our API error messages."
• "Edit the existing deploy-checklist skill so the trigger description is more accurate."
• "Before we deploy this skill, check whether it actually changes how the agent behaves."
• "Should this be a skill, or is it just a rule for our CLAUDE.md file?"

What does a typical session look like?

Suppose you want a skill that tells the agent how to handle a recurring type of bug. The skill guides you to first run a baseline scenario without the skill and record the exact excuses the agent gives for skipping the rule. You then write the skill against those specific failures, rerun the scenario, and add explicit counters for any new excuses that appear.

The source names the three phases as red (the agent breaks the rule without the skill), green (the agent follows the rule with the skill) and refactor (close loopholes while keeping compliance).

What do you need before you start?

The skill itself is a set of Markdown and one script. The source lists these requirements:

• Node.js, version 20 or later, to run render-graphs.js (the repo declares node 20 or later)
• Graphviz installed on the system, providing the dot command, only if you use render-graphs.js
• A runtime with subagent capability for the recommended baseline testing method
• The testing method described relies on manually run subagent scenarios, so it is not an automated test suite

How do you render a skill's flowcharts?

The included render-graphs.js script turns DOT flowcharts in a skill into SVG images so a human can review them. Run it from the directory that holds the scripts, pointing it at the skill folder. Use the second form to merge all diagrams into one SVG.

The script is optional. The rest of the skill works without Graphviz or Node.js.

What are the safety notes?

This skill runs scripts: render-graphs.js is included and runs when you execute it. According to the listing, the skill does not use the network. Read the script before running it on a machine you care about, and only run it on skill folders you trust.

The source also says to call bundled scripts through an interpreter (for example bash scripts/tool.sh or node scripts/tool.js) rather than by bare path, because some plugin packagers strip the executable bit and the bare path fails with Permission denied.

What tips help you write better skills?

The source gives concrete rules that apply to any skill you write. Start with the description, because it decides whether the skill is ever loaded. Keep the body short, since a loaded skill competes with the rest of the conversation for context. Use one good example rather than several weak ones.

• Write descriptions in the third person that describe only when to use the skill, not what it does
• Do not summarise the workflow in the description; the source found the agent then skipped the full skill body
• Use names with verbs first, such as creating-skills or condition-based-waiting
• Refer to other skills by name with a clear required marker rather than using @ links, which load the file immediately
• Use flowcharts only for non-obvious decisions, and use tables, lists or code blocks for everything else