This page is the mandatory deployment checklist for every new skill. It consolidates the verification gates from the RED-GREEN-REFACTOR cycle into a sequential list of pass/fail checks that must be completed before a skill is committed. For the underlying rationale behind each check, see the related pages:
SKILL.md file format and structure: 8.2The checklist is divided into four sequential phases. No phase may be skipped. The Iron Law from skills/writing-skills/SKILL.md374-393 applies unconditionally:
NO SKILL WITHOUT A FAILING TEST FIRST
All checklist items must be tracked with TodoWrite so that progress is visible and cannot be silently abandoned.
Skill Creation Checklist — Phase Summary
Sources: skills/writing-skills/SKILL.md596-634
These checks confirm that baseline behavior was observed before the skill was written. A skill written without a failing baseline is an untested skill.
| # | Check | Pass Criteria |
|---|---|---|
| R1 | Pressure scenarios created | ≥ 3 combined pressures for discipline skills |
| R2 | Scenarios run without skill present | Agent behavior documented verbatim |
| R3 | Rationalization patterns identified | Specific excuses recorded for later countering |
The scenarios must use combined pressure types (time pressure, sunk cost, authority, economic, exhaustion, social, pragmatic). Single-pressure scenarios are insufficient for discipline-enforcing skills.
Baseline documentation must capture:
Sources: skills/writing-skills/SKILL.md537-544 skills/writing-skills/SKILL.md601-603
These checks verify the SKILL.md file is structurally and semantically correct.
Frontmatter Field Constraints
Sources: skills/writing-skills/SKILL.md96-103 skills/writing-skills/SKILL.md606-609
| # | Check | Pass Criteria |
|---|---|---|
| G1 | name field valid | Letters, numbers, hyphens only — no parentheses or special characters |
| G2 | YAML frontmatter valid | Only name and description fields; total ≤ 1024 characters |
| G3 | Description starts with Use when... | Literal string at start of description value |
| G4 | Description is third person | No "I", "we", "you" as subject |
| G5 | Description contains triggering conditions only | No workflow summary or process description |
| G6 | Keyword coverage present | Error messages, symptoms, tool names, synonyms throughout body |
| G7 | Overview states core principle | 1–2 sentences; answers "what is this?" |
| G8 | Addresses baseline failures | Skill body responds to rationalizations found in RED phase |
| G9 | Code inline or linked to file | No orphaned references to non-existent files |
| G10 | One excellent example | Single language; complete and runnable; real scenario |
| G11 | Scenarios run with skill present | Agent complies with all scenarios that previously failed |
The most common failure at G5 is summarizing the skill's workflow in the description. See 8.4 for why this causes agents to skip the skill body. The rule: description = when to trigger, not what to do.
Sources: skills/writing-skills/SKILL.md605-615 skills/writing-skills/SKILL.md150-172
After the skill passes its initial GREEN verification, re-run scenarios to find new rationalizations the agent produces when the original excuses are blocked.
Loophole Discovery and Closure Cycle
Sources: skills/writing-skills/SKILL.md554-555 skills/writing-skills/SKILL.md617-621
| # | Check | Pass Criteria |
|---|---|---|
| RF1 | New rationalizations identified | Additional test runs completed after GREEN |
| RF2 | Explicit counters added | Each rationalization has a named, specific counter in the skill body |
| RF3 | Rationalization Table built | Table covers all excuses from all test iterations |
| RF4 | Red Flags list created | Self-check list that agents can use when tempted to rationalize |
| RF5 | Re-tested until bulletproof | Skill holds under maximum combined pressure with no violations |
For discipline-enforcing skills, the Rationalization Table and Red Flags list are required. For technique or reference skills, RF2–RF4 may be simplified but RF1 and RF5 still apply.
Sources: skills/writing-skills/SKILL.md496-523 skills/writing-skills/SKILL.md617-621
These checks are format and content quality gates independent of the TDD cycle.
| # | Check | Pass Criteria |
|---|---|---|
| Q1 | Flowchart used appropriately | Present only for non-obvious decision points; absent otherwise |
| Q2 | Quick Reference table present | Scannable summary of common operations |
| Q3 | Common Mistakes section present | Each mistake has a problem + fix pair |
| Q4 | No narrative storytelling | No "in session 2025-10-03 we found..." passages |
| Q5 | Supporting files justified | Extra files only for tools or heavy reference (100+ lines) |
When to include a flowchart vs. another format:
Sources: skills/writing-skills/SKILL.md291-315 skills/writing-skills/SKILL.md624-629
| # | Check | Pass Criteria |
|---|---|---|
| D1 | Committed to git | Skill is in version control |
| D2 | Contribution considered | If broadly useful: PR opened against obra/superpowers-skills |
Do not commit until all prior phases are complete. Do not batch-create skills and commit them together — each skill must complete the full checklist before work on the next skill begins.
Sources: skills/writing-skills/SKILL.md583-594 skills/writing-skills/SKILL.md631-633
The following table maps every check to its source location in the writing-skills skill file.
| Phase | ID | Check | File Location |
|---|---|---|---|
| RED | R1 | Pressure scenarios created | skills/writing-skills/SKILL.md601 |
| RED | R2 | Scenarios run without skill | skills/writing-skills/SKILL.md602 |
| RED | R3 | Rationalization patterns documented | skills/writing-skills/SKILL.md603 |
| GREEN | G1 | name valid characters | skills/writing-skills/SKILL.md606 |
| GREEN | G2 | Frontmatter valid YAML, ≤ 1024 chars | skills/writing-skills/SKILL.md607 |
| GREEN | G3 | Description starts with Use when... | skills/writing-skills/SKILL.md608 |
| GREEN | G4 | Description is third person | skills/writing-skills/SKILL.md609 |
| GREEN | G5 | Keywords present throughout | skills/writing-skills/SKILL.md610 |
| GREEN | G6 | Clear overview with core principle | skills/writing-skills/SKILL.md611 |
| GREEN | G7 | Addresses specific baseline failures | skills/writing-skills/SKILL.md612 |
| GREEN | G8 | Code inline or linked | skills/writing-skills/SKILL.md613 |
| GREEN | G9 | One excellent example | skills/writing-skills/SKILL.md614 |
| GREEN | G10 | Scenarios pass with skill present | skills/writing-skills/SKILL.md615 |
| REFACTOR | RF1 | New rationalizations found | skills/writing-skills/SKILL.md617 |
| REFACTOR | RF2 | Explicit counters added | skills/writing-skills/SKILL.md618 |
| REFACTOR | RF3 | Rationalization Table built | skills/writing-skills/SKILL.md619 |
| REFACTOR | RF4 | Red Flags list created | skills/writing-skills/SKILL.md620 |
| REFACTOR | RF5 | Re-tested until bulletproof | skills/writing-skills/SKILL.md621 |
| Quality | Q1 | Flowchart only where needed | skills/writing-skills/SKILL.md625 |
| Quality | Q2 | Quick Reference table present | skills/writing-skills/SKILL.md626 |
| Quality | Q3 | Common Mistakes section present | skills/writing-skills/SKILL.md627 |
| Quality | Q4 | No narrative storytelling | skills/writing-skills/SKILL.md628 |
| Quality | Q5 | Supporting files justified | skills/writing-skills/SKILL.md629 |
| Deployment | D1 | Committed to git | skills/writing-skills/SKILL.md632 |
| Deployment | D2 | Contribution considered | skills/writing-skills/SKILL.md633 |
Sources: skills/writing-skills/SKILL.md596-634
SKILL.md Structure MapThe following diagram associates each checklist check with the section of the SKILL.md file it validates.
Sources: skills/writing-skills/SKILL.md93-137 skills/writing-skills/SKILL.md596-634
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.