Writing Skills Guide
Guides an agent to create, edit, and test skills using a test-driven documentation process
- Repository
- obra/superpowers
- Stars
- 310,931
- Licence
- MIT
- Files
- 9 files
What it does
Once installed, the agent follows a structured method for writing agent skills: it treats each new or edited skill like test-driven development, first running a baseline scenario without the skill, then writing the skill document, then checking that the agent complies and closing any loopholes it finds. It also gives guidance on skill structure, descriptions that trigger correctly, when to split content into separate reference files, and when to add flowcharts. A bundled Node.js script can render Graphviz diagrams from a skill's flowcharts into SVG files.
Great for
- Developers who are building or maintaining their own agent skills
- Teams that want consistent, tested skill documentation before sharing skills across projects
- People who want an agent to review whether a skill description triggers reliably
Skip it if
- People who only want to use existing skills, since this one is for authoring them
- Simple one-off instructions that belong in a project's own instructions file, which the skill itself says should not become a skill
- Anyone expecting it to run tests automatically: the testing method relies on the user or agent running subagent scenarios manually
Try asking
- “Create a new skill for handling database migrations and check that it works before deploying it”
- “Edit my existing code-review skill and verify the changes with pressure scenarios”
- “Shorten this skill's SKILL.md and move the API reference into a separate file”
- “Render the flowcharts in my skill to SVG so I can review the process visually”
Install in 3 steps
- 1
Download the skill
The ZIP contains the 9 original files, the MIT licence and an attribution note.
writing-skills.zip - 2
Add it to your agent
Claude Code (all projects)
mkdir -p ~/.claude/skills && unzip writing-skills.zip -d ~/.claude/skills/Claude Code / Agent SDK (this project only)
mkdir -p .claude/skills && unzip writing-skills.zip -d .claude/skills/Claude apps (web/desktop): Settings → Capabilities → Skills → Upload skill, and choose the ZIP.
- 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
- Run a baseline scenario without the skill first, so you can see the exact rationalizations the agent uses before you write the rules
- Keep the skill description focused on when to use it, not a summary of the workflow, as the skill itself recommends
- Only run render-graphs.js on skills you trust, since it executes locally and reads the SKILL.md file
What's inside
- references/anthropic-best-practices.md
- references/bulletproofing.md
- references/CLAUDE_MD_TESTING.md
- references/discovery.md
- references/flowcharts.md
- references/persuasion-principles.md
- references/testing-skills-with-subagents.md
- render-graphs.js
- SKILL.md
Redistributed unmodified from obra/superpowers 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.