Writing skills skill: how Superpowers tests a SKILL.md before you ship it

Source: obra/superpowers · Maintainer: community: Jesse Vincent (Prime Radiant) · License: MIT · Checked: 24 October 2026

What is the writing skills skill?

The writing skills skill is a guide for creating, editing and testing Agent Skills, built on one idea: you don't know a skill works until you've watched an agent fail without it. It applies test-driven development to SKILL.md files, with subagent pressure scenarios as the tests.

It ships in Superpowers, the open source skill library by Jesse Vincent and Prime Radiant, and the README's contributing section tells people to follow it when they create or change skills. The skill's description reads: "Use when creating new skills, editing existing skills, or verifying skills work before deployment".

The SKILL.md opens with its thesis in bold: "Writing skills IS Test-Driven Development applied to process documentation." As of 24 October 2026, its skills.sh page listed about 218,000 installs (snapshot, 24 October 2026).

What does it do?

The SKILL.md maps each part of TDD onto skill writing:

Its Iron Law is "NO SKILL WITHOUT A FAILING TEST FIRST", and it applies to edits as well as new skills. Write a skill before testing it, and the instruction is to delete it and start over.

Beyond the cycle, it covers:

• When to write a skill. Yes for techniques that weren't obvious and that you'd reuse across projects; no for one-off fixes, project conventions (those go in your instructions file) or anything a regex or validator could enforce.
• Skill types. Technique, pattern and reference skills, each tested differently. Discipline skills get pressure scenarios that combine time pressure, sunk cost and exhaustion; reference skills get retrieval tests.
• Matching the form to the failure. If the agent knows a rule and skips it, use a prohibition with a rationalization table and red flags. If the output has the wrong shape, write a positive recipe instead; the skill reports that prohibitions did worse than recipes in its wording tests.
• Micro-tests for wording. One fresh-context sample per call, always a no-guidance control, at least five repetitions per variant, and every flagged match read by hand.
• A checklist. Red, green and refactor items, quality checks, and a reminder not to batch several untested skills.

What's in the folder:

• SKILL.md: the cycle, the rules and the checklist.
• references/discovery.md: the SKILL.md template, how to write the description, naming and token budgets.
• references/testing-skills-with-subagents.md: the full method for pressure scenarios.
• references/bulletproofing.md and references/persuasion-principles.md: closing loopholes, and the persuasion research the author draws on.
• references/flowcharts.md and references/graphviz-conventions.dot: when a flowchart earns its place and how to style it.
• references/anthropic-best-practices.md: Anthropic's skill authoring best practices, kept as a reference file.
• references/CLAUDE_MD_TESTING.md: a worked test campaign.
• render-graphs.js: a Node script that renders a skill's dot diagrams to SVG.

How do you install the writing skills skill?

As part of Superpowers in Claude Code. The Superpowers README installs it from Anthropic's official marketplace:

/plugin install superpowers@claude-plugins-official

Plugin skills are namespaced as /plugin-name:skill-name per the Claude Code skills docs, so it appears as /superpowers:writing-skills. The README also documents the obra/superpowers-marketplace route and installs for Codex, Cursor, Gemini CLI and other agents.

Just this skill. The skills CLI copies one folder, as shown on the skills.sh page:

npx skills add https://github.com/obra/superpowers --skill writing-skills

Add -g to install for all projects. The folder lands in .claude/skills/writing-skills/ in your project, or ~/.claude/skills/writing-skills/ with -g. Codex and Cursor read the same SKILL.md format; see Codex skills and Cursor skills.

The SKILL.md lists superpowers:test-driven-development as required background, so if you copy single skills, add --skill test-driven-development to the same command.

How does it compare with skill-creator?

Anthropic's skill-creator solves the same problem from a different angle. Its own description covers creating and editing skills, running evals, benchmarking "with variance analysis", and optimizing a skill's description for triggering.

They agree on more than they differ. Anthropic's skill authoring best practices also say to "Create evaluations BEFORE writing extensive documentation," and writing-skills keeps that guide as a reference file. Use skill-creator to measure whether a skill produces good output; use writing-skills when the risk is an agent skipping a rule under pressure.

How do you use it?

Call it when you start or change a skill. It is long, so it works best in a session dedicated to that one skill.

Example prompts (suggestions, not quotes from the repo):

• /superpowers:writing-skills I want a skill that stops the agent from editing generated files. Start with a baseline scenario.
• Our deploy-checklist skill gets skipped when I say it's urgent. Run pressure tests and close the loopholes.
• Review the description of skills/pdf-forms/SKILL.md against the writing-skills discovery rules.
• Render the flowcharts in skills/release/SKILL.md so I can check them.

Requirements: an agent that can run subagents for the pressure tests. render-graphs.js needs Node and Graphviz's dot command installed. The flowchart reference runs it as node ./render-graphs.js ../some-skill from the writing-skills folder.

For the basics of the file itself, the two required fields and where to save it, see how to write a SKILL.md. If you'd rather start from a prompt you already use, the free SKILL.md generator turns it into a first draft in the browser, which you can then test with this skill.

Tips and limits

From the files, not from testing:

• Name casing. The discovery template's example name uses capital letters, but Anthropic's best practices require name to be lowercase letters, numbers and hyphens, max 64 characters, with description max 1,024 characters. Follow the lowercase rule.
• Testing costs tokens. Pressure scenarios and five-repetition micro-tests mean many agent runs per skill. That is the method, not a side effect.
• It is opinionated. It favors strong imperative wording for discipline skills, backed by its persuasion-principles reference. Use the recipe form it describes for skills about output shape.
• What runs. Only render-graphs.js, and only if you or the agent run it. It extracts dot blocks from a SKILL.md and calls the dot binary.
• Audits. As of 24 October 2026, skills.sh showed Gen Agent Trust Hub as Warn (medium risk), citing the script's use of the dot command on content from SKILL.md and the persuasion-principles file as prompt injection patterns. Socket and Snyk showed Pass.
• License. Superpowers is MIT, so you can copy and edit the skill if you keep the copyright notice.

Save it in your Kipt library

In Kipt, open Skills and paste the skill's GitHub folder link into the import box. Kipt reads the SKILL.md and its files, including the references/ folder and render-graphs.js; for a repo with many skills it shows a list to pick from, so you can take test-driven-development in the same import. You can also drop the folder or a .zip. Your skills live in your own private GitHub repo and install into Claude Code or Codex with one command:

npx skills add https://github.com/<you>/<repo>.git --all -g

Kipt is not affiliated with Jesse Vincent, Prime Radiant or Superpowers.

Similar skills

• Skill creator: Anthropic's eval-driven skill for building and tuning skills.
• How to write a SKILL.md: the file format, fields and a full example.
• Superpowers skills: the library writing-skills was built to maintain.
• Verification before completion skill: a short discipline skill that shows the style writing-skills teaches.