obra/superpowers · skills/writing-skills/SKILL.md
writing-skills
“Skill-writing as TDD: make an agent fail first, then write the fix. Sharp method, strict, leans on unseen files”
What it does
Treats writing an agent skill like test-driven development. You run pressure scenarios on a subagent without the skill, record how it fails, write the smallest skill that fixes that, then retest and close loopholes. It adds wording micro-tests and a creation checklist.
- When the agent uses it
- When the agent is asked to create a new skill, edit an existing one, or check that a skill works before deploying it.
- Who it is for
- For people building skills inside the superpowers set who will spend time testing. Skip it if you want a quick SKILL.md template or don't use superpowers.
- What it costs
- 285 lines, about 4.5k tokens once the agent loads it.
Use when creating new skills, editing existing skills, or verifying skills work before deployment
What it tells the agent to do
- Run pressure scenarios on a subagent without the skill and record its choices and rationalizations verbatim.
- Classify the failure and match the form: prohibition, positive recipe, required slot, or conditional.
- Micro-test the wording with fresh-context samples, a no-guidance control, 5+ reps, and every match read by hand.
- Write the minimal skill for those failures, then rerun the same scenarios with it present.
- Close loopholes: counter new rationalizations, build a rationalization table and red flags, retest.
- Work the checklist as todos, one skill at a time, then commit and push to your fork if configured.
Lines worth reading
Straight from the file, with why each one matters.
line 3Use when creating new skills, editing existing skills, or verifying skills work before deployment
The whole trigger. It deliberately says only when, never what, because the skill claims a workflow summary gets followed instead of the skill.
line 171Write skill before testing? Delete it. Start over.
The Iron Law, applied to edits too. Pure discipline, and an agent taking it literally could throw away your work.
line 300If the control doesn't exhibit the failure, there is nothing to fix — stop, don't author the guidance.
The rarest advice in skill-writing: sometimes the right skill is no skill. A no-guidance control keeps you honest.
line 161some harness plugin packagers strip executable bits
A hard-won practical trick: call scripts through bash or node, not by bare path, or they fail with Permission denied.
line 132You're good at porting - one great example is enough.
Flattering the model to stop it writing the same example in five languages.
Watch out for
- Medium
Tells the agent to delete a skill written or edited before testing, with no step that asks the user first. A literal agent could discard work.
line 171Write skill before testing? Delete it. Start over.
- Low
The deployment checklist includes pushing to a remote. It is conditional, but there is no step to confirm with the user first.
line 385Commit skill to git and push to your fork (if configured)
- Low
Micro-tests and pressure scenarios mean many API calls or subagent runs (5+ reps per variant). Cost and time add up without warning.
line 299a raw API call, or a single-shot subagent
The scorecard
- TriggerSays when to use it6/10
Clear 'Use when'; lacks words like SKILL.md, agent skill, frontmatter
- FocusOne clear job7/10
One job, writing tested skills, though it also covers types, layout and examples
- LeanLight to load6/10
About 400 lines; offloads to references, but repeats the test-first sermon several times
- ConcreteSteps you can follow7/10
Real RED-GREEN cycle, micro-test recipe and checklist; scenario how-to lives elsewhere
- SafeSafe to run7/10
No network grabs or secrets; does say delete untested work and push, without asking
What it does well
- The 'Match the Form to the Failure' table gives a testable reason to pick recipe vs prohibition, not just taste.
- The micro-test rules (a control, 5+ reps, read every match, variance as a metric) are rigorous and rare in skill guides.
- Practices what it preaches: detail like flowcharts, discovery and bulletproofing is pushed into linked reference files.
How it could be better
Ask before deleting or pushing
The Iron Law and the deployment checklist let an agent discard or publish work on its own reading of the rules.
AddIf a skill was written or edited before a failing test, tell the user and ask whether to set it aside or delete it. Never delete files or push to a remote without the user's confirmation.
Make it work without its sibling files
It requires superpowers:test-driven-development and four reference files that could not be found next to it, so outside the full set key steps point nowhere.
AddIf references/testing-skills-with-subagents.md is missing, use this minimal pressure scenario: give a subagent <task that tempts the failure> plus <time pressure> and <sunk-cost pressure>, record its reply verbatim, and count it as RED if it <observable violation>.
Add the words a request would use
Requests say 'SKILL.md', 'agent skill' or 'test my skill', and none of those appear in the description.
Adddescription: Use when creating, editing or testing an agent skill (SKILL.md): writing a new skill, changing its name, description or frontmatter, or verifying it works before deployment.
Say 'test first' once, not four times
The Iron Law, the rationalization table, the STOP section and the second REQUIRED BACKGROUND repeat one rule and cost context every load.
Add## The Iron Law NO SKILL OR EDIT WITHOUT A FAILING TEST FIRST. One skill at a time; finish its checklist before the next. Excuses and counters: see references/bulletproofing.md.
Kin reviews against Anthropic’s Extend Claude with skills and agentskills.io’s the Agent Skills standard. It reads SKILL.md only, so a script beside it can still do things the file does not say.