Key Skills Reference

Relevant source files

• .cursor-plugin/plugin.json
• README.md
• skills/brainstorming/SKILL.md
• skills/using-superpowers/SKILL.md

Purpose and Scope

This page is a quick-reference index for the most important skills in the Superpowers library. For concept definitions, see page 3.1 (What Are Skills). For detailed per-skill documentation, see sub-pages 7.1–7.5. For creating new skills, see page 8.

Skill File Layout

Each skill lives in its own directory under skills/. Every skill directory contains at minimum a SKILL.md file with YAML frontmatter (name, description) and Markdown content. Many skills include supporting files (scripts, templates, agent prompts).

skills/
├── using-superpowers/SKILL.md              # Meta-skill (bootstrap)
├── brainstorming/SKILL.md                  # Design phase
├── writing-plans/SKILL.md                  # Task breakdown
├── executing-plans/SKILL.md                # Batch execution
├── subagent-driven-development/SKILL.md    # Automated per-task execution
│   ├── implementer-prompt.md
│   ├── spec-reviewer-prompt.md
│   └── code-quality-reviewer-prompt.md
├── test-driven-development/SKILL.md        # TDD enforcement
│   └── testing-anti-patterns.md
├── systematic-debugging/SKILL.md           # Root-cause debugging
│   ├── root-cause-tracing.md
│   ├── defense-in-depth.md
│   ├── condition-based-waiting.md
│   └── find-polluter.sh
├── using-git-worktrees/SKILL.md            # Workspace isolation
├── finishing-a-development-branch/SKILL.md # Integration options
├── requesting-code-review/SKILL.md         # Review dispatch
├── receiving-code-review/SKILL.md          # Review response
├── verification-before-completion/SKILL.md # Completion gate
├── dispatching-parallel-agents/SKILL.md    # Concurrent subagents
└── writing-skills/SKILL.md                 # Skill authoring guide

Sources: skills/using-superpowers/SKILL.md1-5 skills/brainstorming/SKILL.md1-5 README.md98-121

Core Skill Categories

Skills are organized into functional categories based on their role in the development lifecycle:

Category	Purpose	Skills
Meta	Bootstrap, discovery, enforcement	using-superpowers
Process	Workflow orchestration	brainstorming, writing-plans, executing-plans, subagent-driven-development
Development	Implementation practices	test-driven-development, systematic-debugging, verification-before-completion
Git Workflow	Version control patterns	using-git-worktrees, finishing-a-development-branch
Collaboration	Review, feedback, concurrency	requesting-code-review, receiving-code-review, dispatching-parallel-agents
Meta-Authoring	Creating and testing skills	writing-skills

Sources: README.md98-121

Skill Discovery and Invocation Sequence

The following diagram shows how skills are discovered and invoked, from session start through execution. Key code entities are resolveSkillPath and findSkillsInDir in lib/skills-core.js.

Diagram: Skill Discovery and Invocation — from session bootstrap to SKILL.md execution

Sources: skills/using-superpowers/SKILL.md1-96 lib/skills-core.js

The Meta-Skill: using-superpowers

skills/using-superpowers/SKILL.md is injected into every session via hooks/session-start.sh before the agent's first response. It is the enforcement layer for the entire skill system. Full reference: page 7.1.

Core Enforcement Mechanisms

The Rule: Invoke relevant or requested skills before any response or action.

The 1% Threshold: If there is even a 1% chance a skill applies, invoke it.

TodoWrite Integration: When an invoked skill contains a checklist, the agent must create one TodoWrite todo per checklist item before beginning work.

EnterPlanMode Gate: Before entering plan mode, the agent must verify that brainstorming has already occurred; if not, it must invoke brainstorming first.

Red Flags (Rationalization Prevention)

skills/using-superpowers/SKILL.md57-74 lists rationalizations the agent must treat as stop signals:

Rationalization	Reality
"This is just a simple question"	Questions are tasks. Check for skills.
"I remember this skill"	Skills evolve. Read current version.
"Let me gather information first"	Skills tell you HOW to gather information.
"This feels productive"	Undisciplined action wastes time. Skills prevent this.
"I know what that means"	Knowing concept ≠ using the skill. Invoke it.

Skill Priority Order

skills/using-superpowers/SKILL.md75-84 specifies:

1. Process skills first (brainstorming, systematic-debugging) — determine HOW to approach
2. Implementation skills second (domain-specific) — guide execution

Sources: skills/using-superpowers/SKILL.md1-96

Process Skills Workflow

Process skills define the mandatory development lifecycle. The diagram below maps each workflow stage to its SKILL.md file and key enforcement mechanism.

Diagram: Process Workflow — skill files and enforcement gates

Sources: skills/brainstorming/SKILL.md1-97 README.md80-93

brainstorming

File: skills/brainstorming/SKILL.md — full reference: page 7.2.

Purpose: Enforce design-before-implementation with a HARD-GATE that prevents jumping to code.

Key Features:

• Six-item ordered checklist (skills/brainstorming/SKILL.md23-31) that must be tracked via TodoWrite
• Anti-pattern callout: "This Is Too Simple To Need A Design" — applies to every project
• HARD-GATE block (skills/brainstorming/SKILL.md14-16): no implementation until design approved
• Design doc written to docs/plans/YYYY-MM-DD-<topic>-design.md
• Terminal state is invoking writing-plans; no other skill may follow

When to Invoke: Any creative work — creating features, building components, adding functionality, or modifying behavior.

Sources: skills/brainstorming/SKILL.md1-97

writing-plans

File: skills/writing-plans/SKILL.md — full reference: page 6.4.

Purpose: Break approved designs into bite-sized tasks with TDD steps and exact file paths.

Key Features:

• Tasks granular enough to complete in 2–5 minutes
• Each task includes explicit RED-GREEN-REFACTOR steps
• Exact file paths and verification commands per step
• Plans stored in docs/plans/YYYY-MM-DD-<feature>.md
• Output consumed by either executing-plans or subagent-driven-development

When to Invoke: After brainstorming produces an approved design.

Sources: skills/writing-plans/SKILL.md README.md83-84

executing-plans and subagent-driven-development

Files: skills/executing-plans/SKILL.md, skills/subagent-driven-development/SKILL.md — full references: pages 6.5, 6.6.

Two execution modes for implementing plans:

Attribute	executing-plans	subagent-driven-development
Batch size	3 tasks	1 task
Human checkpoints	Between batches	On request
Review mechanism	requesting-code-review	spec-reviewer-prompt.md + code-quality-reviewer-prompt.md
Subagent dispatch	Manual	Via Task tool per task
Best for	Exploratory work	Autonomous runs

Supporting templates (subagent-driven-development):

• skills/subagent-driven-development/implementer-prompt.md — worker instructions + self-review checklist
• skills/subagent-driven-development/spec-reviewer-prompt.md — skeptical requirements verification
• skills/subagent-driven-development/code-quality-reviewer-prompt.md — code quality review criteria

Both modes require using-git-worktrees before starting.

Sources: skills/executing-plans/SKILL.md skills/subagent-driven-development/SKILL.md README.md86-87

Development Practice Skills

test-driven-development

File: skills/test-driven-development/SKILL.md — full reference: page 7.3.

The Iron Law: NO PRODUCTION CODE WITHOUT A FAILING TEST FIRST

RED / GREEN / REFACTOR cycle:

1. RED — Write minimal failing test that demonstrates the requirement; verify it fails
2. GREEN — Write minimal production code to make the test pass; verify it passes
3. REFACTOR — Improve structure while keeping tests green; verify again

Supporting file: skills/test-driven-development/testing-anti-patterns.md — covers mocking without understanding dependencies, testing mock behavior instead of real behavior, adding test-only methods to production classes.

When to Invoke: Any production code implementation, especially within executing-plans or subagent-driven-development.

Sources: skills/test-driven-development/SKILL.md README.md101-102

systematic-debugging

File: skills/systematic-debugging/SKILL.md — full reference: page 7.4.

The Iron Law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST

Four mandatory phases:

1. Root Cause Investigation — reproduce reliably, gather evidence
2. Pattern Analysis — identify systemic patterns
3. Hypothesis and Testing — form and verify hypotheses
4. Implementation — targeted fix based on confirmed root cause

Bundled techniques and tools:

File	Purpose
root-cause-tracing.md	Trace bugs backward through call stack
defense-in-depth.md	Add validation at multiple layers
condition-based-waiting.md	Replace arbitrary timeouts with condition polling
find-polluter.sh	Bisection script for test-order pollution

When to Invoke: Any unexpected behavior, test failure, or bug report.

Sources: skills/systematic-debugging/SKILL.md README.md104-105

Git Workflow Skills

using-git-worktrees

File: skills/using-git-worktrees/SKILL.md — full reference: page 6.3.

Purpose: Create isolated workspace before any implementation begins.

Key operations:

• Directory: .worktrees/ (project-local) or ~/.config/superpowers/worktrees/ (global)
• Safety: git check-ignore to verify worktree directory is excluded; confirm clean baseline
• Setup: create branch from HEAD, copy config files, install dependencies
• Cleanup: remove worktree, optionally delete branch after integration

Integration requirement: Both subagent-driven-development and executing-plans require this skill before implementation.

Sources: skills/using-git-worktrees/SKILL.md README.md82

finishing-a-development-branch

File: skills/finishing-a-development-branch/SKILL.md — full reference: page 6.8.

Purpose: Handle branch integration with four explicit options after work is complete.

Four options:

1. Merge locally — integrate directly into main branch
2. Push PR — create pull request for external review
3. Keep as-is — preserve branch for later
4. Discard — delete branch and worktree

Required gate: All tests must pass before any option is chosen.

When to Invoke: After completing all tasks in the execution phase.

Sources: skills/finishing-a-development-branch/SKILL.md README.md92

Collaboration and Quality Skills

requesting-code-review

File: skills/requesting-code-review/SKILL.md — full reference: page 6.7.

Purpose: Dispatch the code-reviewer agent to review committed work.

Process:

• Dispatch superpowers:code-reviewer via Task tool with BASE_SHA and HEAD_SHA parameters
• Agent reviews against plan requirements and code quality criteria
• Issues classified as: critical (blocks progress), important, minor
• Review loop: implementer fixes critical issues, reviewer verifies again

Agent definition: agents/code-reviewer.md

Sources: skills/requesting-code-review/SKILL.md agents/code-reviewer.md1-49

receiving-code-review

File: skills/receiving-code-review/SKILL.md — full reference: page 7.5.

Purpose: Structured response to review feedback.

Key rules:

• Reply inline, not as top-level comments
• Address every comment explicitly
• Commit fixes with clear messages referencing the comment
• Re-request review after all feedback addressed

Sources: skills/receiving-code-review/SKILL.md README.md114

writing-skills

File: skills/writing-skills/SKILL.md — full reference: page 8.

Purpose: Guide skill creation using TDD methodology and Claude Search Optimization (CSO).

Skill TDD cycle:

1. RED — Write pressure scenario; verify agent fails without skill
2. GREEN — Write minimal SKILL.md that passes the scenario
3. REFACTOR — Add pressure resistance (time, sunk cost, authority scenarios)

Claude Search Optimization (CSO):

• description field must be triggers only: "Use when..." format, ≤1024 chars
• Never summarize workflow in description — doing so causes agents to skip the skill body

Sources: skills/writing-skills/SKILL.md README.md119-120

Quick Reference: When to Use Which Skill

Trigger	Required Skill(s)	SKILL.md Path
"Build / create / add feature X"	brainstorming → writing-plans	skills/brainstorming/SKILL.md
"Design done, now implement"	writing-plans → execution	skills/writing-plans/SKILL.md
"Execute this plan"	using-git-worktrees → executing-plans or subagent-driven-development	skills/using-git-worktrees/SKILL.md
"This test is failing / bug found"	systematic-debugging	skills/systematic-debugging/SKILL.md
"Write this code"	test-driven-development	skills/test-driven-development/SKILL.md
"Task X is done"	requesting-code-review	skills/requesting-code-review/SKILL.md
"Review says fix Y"	receiving-code-review	skills/receiving-code-review/SKILL.md
"Done with this branch"	finishing-a-development-branch	skills/finishing-a-development-branch/SKILL.md
"Create a new skill"	writing-skills	skills/writing-skills/SKILL.md
"Starting a session"	using-superpowers (auto-injected)	skills/using-superpowers/SKILL.md

Sources: skills/using-superpowers/SKILL.md1-96 README.md80-93

Skill Naming and References

All skill references use lowercase kebab-case matching directory names. The superpowers: namespace prefix is the canonical form for cross-skill references:

• ✅ superpowers:test-driven-development
• ✅ superpowers:brainstorming
• ❌ test-driven-development (without namespace, ambiguous in multi-source setups)
• ❌ Test-Driven-Development (wrong case)

Slash commands in commands/ map to skills:

Command	Mapped Skill	File
/brainstorm	superpowers:brainstorming	commands/brainstorm.md
/write-plan	superpowers:writing-plans	commands/write-plan.md
/execute-plan	superpowers:executing-plans	commands/execute-plan.md

All command files set disable-model-invocation: true — these are user-facing only, not agent-invocable.

Sources: commands/brainstorm.md commands/write-plan.md commands/execute-plan.md

Enforcement Mechanisms Reference

Skills use multiple enforcement patterns to prevent bypassing:

Mechanism	Description	Skill / Location
HARD-GATE block	XML-tagged absolute prohibition	skills/brainstorming/SKILL.md:14-16
Iron Law	Bolded absolute rule	skills/test-driven-development/SKILL.md, skills/systematic-debugging/SKILL.md
TodoWrite checklist	One todo per checklist item before starting	skills/using-superpowers/SKILL.md:47-50
EnterPlanMode gate	Must brainstorm before plan mode	skills/using-superpowers/SKILL.md:29-33
Rationalization / Red Flags table	Pre-empts common bypass reasoning	skills/using-superpowers/SKILL.md:57-74
Review loops	Reviewer verifies again after fixes	skills/subagent-driven-development/SKILL.md
GraphViz/Mermaid flowchart	Limits valid state transitions	skills/brainstorming/SKILL.md:35-53

Sources: skills/using-superpowers/SKILL.md1-96 skills/brainstorming/SKILL.md14-16

Skill Update and Synchronization

Skills are automatically synchronized via git operations during session initialization:

Session Start Sequence:

1. hooks/session-start.sh executes before agent's first response
2. git fetch from tracking remote (origin or upstream)
3. git status checks if local is behind
4. git pull --ff-only auto-merges if fast-forward possible
5. If diverged: notify user, recommend pulling-updates-from-skills-repository skill

Manual Sync: Use superpowers:pulling-updates-from-skills-repository skill when automatic fast-forward fails (branch has diverged from upstream).

Skills Location:

• Claude Code: ~/.claude/skills/superpowers/ → symlinks to cloned repo
• OpenCode: ~/.config/opencode/skills/superpowers/ → symlinks to cloned repo
• Codex: ~/.agents/skills/superpowers/ → symlinks to cloned repo

Sources: RELEASE-NOTES.md556-603 RELEASE-NOTES.md32-38

Code Entity Mapping

The following diagram maps skill invocation to concrete code paths and file locations:

Sources: RELEASE-NOTES.md556-608 hooks/session-start.sh (referenced), lib/initialize-skills.sh (referenced), lib/skills-core.js (referenced)