This page covers the methodology, format, and process for authoring new skills in the superpowers library. It explains how the TDD discipline is applied to process documentation, what makes a skill effective, and how to deploy and verify one before committing it.
For details on how existing skills are found and invoked by agents, see Finding and Invoking Skills. For the full reference on any individual built-in skill, see Key Skills Reference.
Creating a skill is not writing documentation—it is Test-Driven Development applied to process documentation. The same Iron Law from test-driven-development applies here without modification:
NO SKILL WITHOUT A FAILING TEST FIRST
The canonical implementation of this process lives in `skills/writing-skills/SKILL.md`
Every concept in the TDD cycle has a direct equivalent in skill creation.
TDD Concepts Mapped to Skill Creation
| TDD Concept | Skill Creation Equivalent |
|---|---|
| Test case | Pressure scenario dispatched to a subagent |
| Production code | The SKILL.md document |
| Watch test fail (RED) | Agent violates rule without the skill (baseline) |
| Watch test pass (GREEN) | Agent complies with skill present |
| Refactor | Find new rationalizations, add explicit counters, re-test |
| Write test first | Run baseline scenario before writing the skill |
| Minimal code | Skill addresses only the specific failures from baseline |
Sources: `skills/writing-skills/SKILL.md32-44
Skills fall into three categories. Each type requires a different testing strategy (see Testing Skills with Pressure Scenarios).
| Type | Definition | Examples |
|---|---|---|
| Technique | Concrete method with sequential steps | condition-based-waiting, root-cause-tracing |
| Pattern | Mental model for a class of problems | flatten-with-flags, test-invariants |
| Reference | API docs, syntax guides, command references | Office docs, library API guides |
Sources: `skills/writing-skills/SKILL.md63-71
Each skill lives in its own subdirectory under skills/. The only required file is SKILL.md.
skills/
skill-name/
SKILL.md # Required — frontmatter + content
supporting-file.* # Optional — only for heavy reference or reusable tools
Supporting files are warranted only when reference material exceeds ~100 lines or when providing a reusable script/template. Everything else stays inline.
Sources: `skills/writing-skills/SKILL.md74-91
Skill Authoring Lifecycle
Sources: `skills/writing-skills/SKILL.md533-560
SKILL.md Structure and Code EntitiesThe diagram below maps the sections of a SKILL.md file to the code constructs and conventions that govern them.
SKILL.md Anatomy
Sources: `skills/writing-skills/SKILL.md93-137 `skills/writing-skills/SKILL.md140-197
The description field in the YAML frontmatter controls whether an agent loads the skill at all. It must describe only triggering conditions, never the workflow inside the skill.
Why this matters: If the description summarizes the workflow, the agent may follow the description as a shortcut and skip the skill body entirely. This was confirmed by testing: a description mentioning "code review between tasks" caused agents to do one review instead of two, because they never read the flowchart that required a two-stage process.
| Pattern | Example | Verdict |
|---|---|---|
| Triggering conditions only | Use when executing implementation plans with independent tasks | ✅ |
| Workflow summary | Use when executing plans - dispatches subagent per task with code review between tasks | ❌ |
| Too abstract | For async testing | ❌ |
| First person | I can help you with async tests | ❌ |
| Technology-specific (non-specific skill) | Use when tests use setTimeout/sleep | ❌ |
The description should also include keyword coverage: error messages, symptom words, tool names, and synonyms that an agent would search for when encountering the relevant problem.
For full CSO guidance, see Claude Search Optimization (CSO).
Sources: `skills/writing-skills/SKILL.md140-197
Different skill types require different testing approaches. The table below maps each type to its test design and success criteria.
| Skill Type | Test Approach | Success Criteria |
|---|---|---|
| Discipline-enforcing | Pressure scenarios with combined stressors (time + sunk cost + exhaustion) | Agent follows rule under maximum pressure |
| Technique | Application scenarios + variation/edge-case scenarios | Agent applies technique correctly to new scenario |
| Pattern | Recognition scenarios + counter-examples | Agent identifies when/how to apply the pattern |
| Reference | Retrieval scenarios + gap testing | Agent finds and correctly uses reference information |
Sources: `skills/writing-skills/SKILL.md395-443
Discipline-enforcing skills must actively resist the rationalizations agents produce under pressure. The writing-skills skill documents the concrete techniques:
Common Rationalizations and Their Reality
| Excuse | Reality |
|---|---|
| "Skill is obviously clear" | Clear to you ≠ clear to other agents. Test it. |
| "Testing is overkill" | Untested skills always have issues. 15 min testing saves hours. |
| "I'll test if problems emerge" | Problems mean agents can't use the skill. Test before deploying. |
| "Academic review is enough" | Reading ≠ using. Test application scenarios. |
| "No time to test" | Deploying untested skill wastes more time fixing later. |
Sources: `skills/writing-skills/SKILL.md459-523
The Iron Law applies to new skills and edits to existing skills.
NO SKILL WITHOUT A FAILING TEST FIRST
If code is written before the test, TDD requires deleting it and starting over. The same applies here:
No exceptions:
Sources: `skills/writing-skills/SKILL.md374-393
This diagram shows how an agent discovers and loads a skill, tracing through the code entities involved.
Skill Discovery: Natural Language to Code Entity Path
Sources: `skills/writing-skills/SKILL.md635-645 `skills/writing-skills/SKILL.md93-100
The full checklist is detailed in Skill Creation Checklist. The phases are:
RED Phase
GREEN Phase
Use when..., triggers only, third personREFACTOR Phase
Deployment
Sources: `skills/writing-skills/SKILL.md596-633
| Page | What It Covers |
|---|---|
| Test-Driven Development for Skills | Full RED-GREEN-REFACTOR cycle adapted for skill authoring |
| SKILL.md Format and Structure | Required YAML fields and Markdown section conventions |
| Testing Skills with Pressure Scenarios | How to construct effective pressure scenarios |
| Claude Search Optimization (CSO) | How the description field controls discoverability |
| Skill Creation Checklist | Deployment checklist for each phase |
| Contributing Skills | Fork and pull request process for the superpowers-skills repository |
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.