writing-skills Skill: Write and Test New Agent Skills

Teaches your agent to write and edit skills the way you write tested code: see an agent fail first, then write the skill that fixes it.

Installs: 224.6K; on skills.sh
Stars: 310.6K; on GitHub
Files: 9; besides SKILL.md
Updated: Oct 2026; last repo commit

The skill applies red-green-refactor to documentation. First you run a pressure scenario with a subagent and note exactly how it breaks the rule without the skill. Then you write the smallest skill that fixes those failures, and finally you close the loopholes the agent finds. It states one rule: if you did not watch an agent fail without the skill, you do not know it teaches the right thing.

It triggers when you create or edit a skill, or check that one works before you deploy it. The SKILL.md says you must understand the test-driven-development skill from the same repo first, so install both. It bundles 8 reference files and one Node script, render-graphs.js, for rendering flowcharts; the script's header says it needs graphviz (dot) installed.

Good for

People writing their own skills for Claude Code, Codex or Gemini CLI
Teams whose skills are ignored or followed only part of the time
Anyone who wants a checklist before they ship a skill

Install writing-skills

Claude Code

Copy this prompt.

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

/plugin install superpowers@claude-plugins-official

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.

Pick one route, not both. The skill says you must understand the test-driven-development skill from the same repo before using it, so the skills CLI route names both. The plugin route installs the whole Superpowers set.

From the project README. Source.

What's in the skill

When it loads

Use when creating new skills, editing existing skills, or verifying skills work before deployment

Sections in SKILL.md

Overview
What is a Skill?
TDD Mapping for Skills
When to Create a Skill
Skill Types
Technique
Pattern
Reference
Directory Structure
Writing SKILL.md
Flowcharts
Code Examples
File Organization
Self-Contained Skill
Skill with Reusable Tool
Skill with Heavy Reference

Key facts

Author: obra (Superpowers)
License: MIT, from the crawl of the repo
Installs on skills.sh: 224,567 (Nov 2, 2026)
GitHub stars: 310,635 for the obra/superpowers repo (Nov 2, 2026)
Last repo commit: Oct 29, 2026
What installs: SKILL.md, 8 reference files and render-graphs.js (9 bundled files besides SKILL.md)
Needs: The test-driven-development skill from the same repo; Node.js and graphviz only for the flowchart script

What it includes

Maps test case, failing test and refactor to pressure scenario, baseline, loopholes
The core idea of the skill, laid out as a table.
TDD mapping for skills
Run a scenario with subagents before writing, and record the excuses they use
You document the exact rationalizations the agent gives.
Runs code · RED: baseline
Write only what fixes those specific failures, then check the agent complies
The description should say only when to use the skill, starting with "Use when".
Write · GREEN: minimal skill
Find new rationalizations, plug them and re-verify
Includes a section on bulletproofing against rationalization.
REFACTOR: close loopholes
Different tests for discipline, technique, pattern and reference skills
Four skill types, each with its own way to test.
Test by skill type
Lists 4 anti-patterns and a skill creation checklist
Anti-patterns: narrative examples, multi-language dilution, code in flowcharts, generic labels.
Anti-patterns and checklist
Best practices, discovery, flowcharts, persuasion, testing with subagents and more
Includes Anthropic's skill authoring best practices, a 46 KB file.
Read · references/ (8 files)
Bundled Node script for rendering flowcharts
Extracts dot blocks from a SKILL.md and renders them to SVG by running graphviz `dot`. The SKILL.md points to references/flowcharts.md for when and how to use one.
Runs code · render-graphs.js

From the official docs

Permissions

Low risk

The skill writes skill files and runs subagent tests plus one Node script. Review new skills and read the script before you rely on it.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It creates files in your skills directory
New skills go in ~/.claude/skills/ or a project folder. Review each skill before relying on it.
It runs subagent tests and one bundled Node script
Read render-graphs.js before running it. Subagents can run commands in your project.
Its checklist includes git commit and push
The deployment checklist says to commit the skill to git and push to your fork if configured. Approve pushes yourself. github.com
It tells the agent to delete skills written before testing
The Iron Law says a skill written before its baseline test should be deleted and restarted. Keep your own copy of anything you want to keep. github.com
Gen Agent Trust Hub shows warn on skills.sh
Socket and Snyk show pass. Check the audit page before you install. skills.sh

Questions

What does writing-skills do?

It guides your agent through creating and testing a skill: baseline test with subagents, a minimal SKILL.md, then loophole fixing. It also sets rules for descriptions, file layout and when not to create a skill.

How do I install it in Claude Code, Cursor or Codex?

Use the install box above. It lists the whole Superpowers plugin and, for Claude Code, a skills CLI command that names both writing-skills and test-driven-development.

Does it need test-driven-development installed too?

Yes. The SKILL.md says you must understand superpowers:test-driven-development before using it, and it adapts that cycle to documentation.

Where do my new skills go?

The SKILL.md says personal skills live in your runtime's skills directory, ~/.claude/skills/ on Claude Code. Codex, Copilot CLI and Gemini CLI also recognize ~/.agents/skills/.

Is it safe?

It writes skill files into your skills directory, runs subagent tests, and bundles one Node script that runs graphviz. Its checklist also includes committing the new skill to git and pushing to your fork if configured. Read the script and approve pushes yourself.

Does it need an API key?

SKILL.md mentions none.

Information

updated Nov 2, 2026

Repository: obra/superpowers
Folder: skills/writing-skills

obra/superpowers skills.sh

Sources

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

Show all 4

obra/superpowers README · github.com
vercel-labs/skills commands · github.com
obra/superpowers writing-skills SKILL.md · github.com
writing-skills render-graphs.js · github.com