Writing Skills (obra/superpowers)

tl;dr: this is the meta-skill in obra/superpowers. Writing a SKILL.md is treated as Test-Driven Development applied to documentation: write a pressure scenario (the failing test), run it on a subagent without the skill (RED), write the skill (GREEN), close loopholes the subagent found (REFACTOR). The “Iron Law” is NO SKILL WITHOUT A FAILING TEST FIRST — same shape as the TDD iron law the rest of the methodology enforces.

What it actually does

The SKILL.md (obra/superpowers, fetched 2026-09-10) reframes skill authorship from “write some docs” to “run an experiment”. Core principle:

If you didn’t watch an agent fail without the skill, you don’t know if the skill teaches the right thing.

The TDD mapping the skill names verbatim:

The description field is the trigger:

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

So writing-skills is not a generic “how to write good docs” skill — it’s the procedure for closing the loop between author and consumer before a skill ships.

When to create a skill

The skill enumerates when to create vs not. Create when:

• Technique wasn’t intuitively obvious to you
• You’d reference this again across projects
• Pattern applies broadly (not project-specific)
• Others would benefit

Don’t create for: one-off solutions, standard practices well-documented elsewhere, project-specific conventions (those go in an instructions file), mechanical constraints that are better automated with regex/validation.

Four skill types, four test forms

The skill classifies skills into four types and prescribes the right test form per type:

• Technique skills (e.g. condition-based-waiting, root-cause-tracing). Test with application + variation + missing-information scenarios. Success = agent applies the technique to a new scenario correctly.
• Pattern skills (mental models like flatten-with-flags, test-invariants). Test with recognition + application + counter-examples. Success = agent identifies when/how and when NOT to apply.
• Reference skills (API docs, command references). Test with retrieval + application + gap testing. Success = agent finds the right info and uses it correctly.
• Discipline-enforcing skills (TDD, verification-before-completion, designing-before-coding). Test with academic questions, pressure scenarios (time + sunk cost + exhaustion), multiple pressures combined. Success = agent follows the rule under maximum pressure.

Discipline skills are where rationalization bulletproofing matters. The skill’s “Match the Form to the Failure” table is the key insight: prohibition-based bulletproofing (“don’t X”) backfires on wrong-shaped output (bloated prompt, buried verdict) — use a positive recipe or contract instead. The skill cites head-to-head wording tests showing that prohibition arms produced more of the unwanted content than no-guidance controls on shaping problems.

The Iron Law and the deployment checklist

The skill is explicit and quotable:

NO SKILL WITHOUT A FAILING TEST FIRST

This applies to NEW skills AND EDITS to existing skills. Write skill before testing? Delete it. Start over. Edit skill without testing? Same violation.

No exceptions:

• Not for “simple additions”
• Not for “just adding a section”
• Not for “documentation updates”
• Don’t keep untested changes as “reference”
• Don’t “adapt” while running tests
• Delete means delete

The deployment checklist the skill mandates — RED phase, GREEN phase, REFACTOR phase, quality checks, deployment — is a todo list, one item per checkbox. The skill says create a todo for each item; “batching” by skipping is itself a violation.

Skill Discovery Optimization (SDO)

Half the skill is about the description field. The rule the upstream text hammers:

Description = When to Use, NOT What the Skill Does.

NEVER summarize the skill’s process or workflow in the description.

Testing showed that when a description summarized the workflow (“code review between tasks”), the agent did ONE review instead of the two reviews the skill flowchart prescribed. When the description was reduced to triggering conditions only (“Use when executing implementation plans with independent tasks in the current session”), the agent read the flowchart and followed both stages. The skill body becomes documentation agents skip when the description is a shortcut.

The skill calls out five other SDO techniques: keyword coverage (error messages, symptoms, synonyms, tool names), descriptive naming (verb-first, gerunds), token efficiency (target word counts — getting-started <150, frequently-loaded <200, other <500), cross-referencing (skill name + explicit requirement markers, never @ links because they force-load and burn 200k+ context), and a flowchart-usage rule (only for non-obvious decisions and loops; never for reference material or code).

Install

The upstream README does not document npx skills add obra/superpowers. Install is per-harness and the README enumerates them. Common paths:

# Claude Code — official Anthropic marketplace
/plugin install superpowers@claude-plugins-official

# Codex CLI — official Codex marketplace
/plugins
# search: superpowers → Install Plugin

# Cursor
/add-plugin superpowers

# Gemini CLI
gemini extensions install https://github.com/obra/superpowers

# OpenCode — host fetches install doc itself
# Say: "Fetch and follow instructions from
#       https://raw.githubusercontent.com/obra/superpowers/main/.opencode/INSTALL.md"

If your host only watches a local SKILL.md, clone the repo:

git clone https://github.com/obra/superpowers
# place at any path your host's skill loader watches:
#   ~/.claude/skills/writing-skills/SKILL.md
#   .claude/skills/writing-skills/SKILL.md

writing-skills requires familiarity with superpowers:test-driven-development as a required background — it adapts TDD, it does not reteach RED-GREEN-REFACTOR. Install that skill too, or the meta-skill’s vocabulary will land without the foundation it builds on.

Gotchas

• It’s not a style guide. writing-skills is a procedure with a fail-first gate. Style choices (sentence case headings, language tags on code blocks) live in config/style_guide.md on this site — not inside this skill.
• Discipline skills need bulletproofing, technique skills don’t. The skill’s “Match the Form to the Failure” table is non-obvious — reach for the wrong form (prohibition on a shaping problem) and the skill measurably backfires per the cited wording tests.
• @ link syntax is forbidden for cross-skill references. It force-loads files and burns 200k+ context. The skill explicitly prefers skill-name + REQUIRED SUB-SKILL: markers.
• Description is the load decision, not a summary. Agents read the description to decide whether to load the skill at all. Summarizing the workflow in the description makes the body skippable. Triggers-only.
• No batching across skills. The skill says: do not create multiple skills in batch without testing each. Moving to the next skill before the current is verified is itself a violation.
• sandbox_test.verdict: untested — we read SKILL.md and the README; we did not run a baseline subagent to RED-then-GREEN a new skill.

Related: Brainstorming (obra/superpowers) — the upstream gate before any skill is written or used; Writing Plans (obra/superpowers) — sibling collaboration skill that decomposes specs into tasks; Using Superpowers (obra/superpowers) — the bootstrap that makes the rest of the methodology trigger automatically.