Core Idea
The author's design philosophy, what sets this apart from peer projects, and quick notes on the key workflows. Skill names mentioned in the text auto-link to their detail pages.
The core idea behind Superpowers is to break the "software development methodology" into many single-purpose, pluggable, model-agnostic micro-skills, then have a session-level bootstrap auto-trigger them at the right moment—shaping agent behavior systematically without altering the agent's underlying capabilities.
Core principles
- Small and focused: each skill does one thing; for example /test-driven-development enforces only the RED-GREEN-REFACTOR loop, while /systematic-debugging handles only four-phase root-cause tracing.
- Composable: skills assemble like Lego on demand; nothing is forced, users pick and combine what their project needs.
- Model- and harness-agnostic: the same set works across Claude Code, Codex, Gemini CLI, OpenCode, Cursor, and more.
- Behavior-shaping first: skills are tuned against real agent behavior and are "code, not prose"; changes require eval evidence.
How it works
When a user gives the AI a development request, the agent does not jump straight into code; it auto-triggers a chain of skills in order:
- Clarify requirements: /brainstorming refines intent via questions, presents the design in sections for confirmation, and saves a design doc.
- Isolate a workspace: /using-git-worktrees sets up an isolated branch and verifies a clean test baseline.
- Decompose the plan: /writing-plans splits work into tiny 2-5 minute steps, each with exact file paths, full code, and verification.
- Execute: /subagent-driven-development or /executing-plans dispatches a fresh subagent per step or executes in batches, with two-stage review.
- Test-driven: /test-driven-development enforces write failing test → make it pass → refactor.
- Code review: /requesting-code-review and /receiving-code-review formalize review and feedback handling.
- Finish: /finishing-a-development-branch decides merge/PR/keep/discard and cleans up the worktree. A meta layer includes /writing-skills (authoring new skills) and /using-superpowers (the bootstrap that locates and uses skills before any response).
Usage advice
- After installation the bootstrap triggers automatically on first work; users rarely invoke skills manually—follow the README's Basic Workflow order.
- When contributing or modifying skills, follow /writing-skills and validate with evals before merging.
Skill Relationships
Skill → Skill usage relationships, with cross-layer references. Same color blocks indicate the same skill form.
Skill Composition
Each skill is designed for a specific kind of caller — some only fire when you name them, others load automatically when the model judges them relevant. The split below summarises both modes at a glance.
These skills only fire when you call them by name. The agent will not load them on its own — they stay inert until invoked.
These skills are loaded automatically by the agent when it judges the context relevant. You usually don't need to call them yourself.
Skill List
Transforms vague ideas into fully-formed designs and specs through collaborative dialogue. Progresses through step-by-step questioning to understand requirements, proposing 2-3 approaches with trade-offs, presenting design in sections, writing a design document, and triggering implementation plan generation. Key outputs are structured design documents and executable implementation plans.
Delegates 2+ independent problem domains to specialized sub-agents for parallel processing. The core method is constructing self-contained agent task instructions for each independent domain (e.g., different test file/subsystem failures), dispatching multiple sub-agents concurrently in one response, and finally reviewing and integrating all fixes. Dramatically improves troubleshooting efficiency for multiple failures.
Responsible for executing a written implementation plan. Loads and reviews the plan, ensures an isolated workspace is ready via using-git-worktrees, then follows each step exactly, runs verifications, and finally invokes the finishing-a-development-branch skill to wrap up. Stops and asks for clarification when blocked, never guessing.
Finalizes a development branch after implementation is complete and tests pass. Core flow: verify full test suite → detect workspace environment (normal repo/worktree/detached HEAD) → determine base branch → present integration options (merge/create PR/keep) → execute choice → clean up workspace. Ensures tests are green before every integration.
A skill for technically rigorous reception of code review feedback. Follows a READ→UNDERSTAND→VERIFY→EVALUATE→RESPOND→IMPLEMENT pattern, forbidding performative agreement. Requires clarification of unclear items before implementation, skeptical evaluation of external reviewer suggestions, and technical pushback when suggestions are wrong. Produces verified, high-quality code changes without regressions from blind adoption.
Proactively dispatch a code reviewer subagent to examine code diffs before issues cascade. Core principle: review early, review often. Provides the reviewer precisely crafted context (never session history) focused on the work product. Outputs review findings (Critical/Important/Minor) and an assessment, helping developers verify work meets requirements before merging.
Execute implementation plans by dispatching a fresh subagent per task, followed by a spec compliance + code quality review after each task, and a broad whole-branch review at the end. Core principle: fresh subagent per task + task review + final review = high quality, fast iteration. Uses a ledger file for progress tracking to survive context compaction. Produces high-quality, multi-review-verified implementation code.
A systematic debugging skill with the iron law: NO FIXES WITHOUT ROOT CAUSE INVESTIGATION FIRST. Four phases: Root Cause Investigation (reproduce, check changes, trace data flow), Pattern Analysis (find working examples, compare), Hypothesis Testing (minimal change to test), Implementation (create failing test first, single fix, verify). If 3+ fixes fail, question the architecture. Produces reliable, tested fixes from root cause analysis, avoiding symptom-fix thrashing.
Test-Driven Development (TDD) skill that mandates writing a failing test before any production code, following the Red-Green-Refactor cycle. Core principle: no production code without a failing test first. Through RED (write failing test, verify failure), GREEN (write minimal passing code, verify pass), and REFACTOR (clean up), it ensures testable code and comprehensive behavior coverage. Delivers high-confidence code with reliable regression test suites.
Git Worktrees skill that ensures development work happens in isolated workspaces. Prioritizes detecting existing isolation first, then using native platform worktree tools, falling back to manual git worktree creation. Includes a three-step process: detect existing isolation (Step 0), create isolated workspace (Step 1), project setup and baseline test verification (Step 2-3). Protects the main branch from in-progress changes.
The entry skill for Superpowers that mandates checking and invoking relevant skills before ANY response or action (with explicit red flags to prevent rationalization). Core rule: if there is even a 1% chance a skill applies, it MUST be invoked. Before entering plan mode, brainstorming skill must be invoked first. For skill priority, process skills come before implementation skills. Includes platform adaptation references for Codex, Pi, and Antigravity.
Verification Before Completion skill with the core principle: evidence before assertions always. Iron Law: no completion claims without fresh verification evidence. Before making any status claim (tests passing, build succeeding, bug fixed, etc.), one must identify the proving command, run it fully, read complete output and exit code, and confirm the output supports the claim. Applies to all success/completion claims, expressions of satisfaction, commits/PR creation, etc.
This skill is used to break down specifications or requirements into executable implementation plans. Through scope checks, file structure mapping, task granularity refinement (each step 2-5 minutes), and self-review, it generates structured Markdown plan documents. Key output is a complete plan with global constraints, task decomposition, precise code examples, and verification steps, enabling follow-through execution with zero decision-making.
This skill applies Test-Driven Development (TDD) methodology to the creation and editing of skill documentation. Core process: first write test cases (pressure scenarios) to observe agent behavior without the skill (RED phase), then write the skill document (GREEN phase), and finally refactor to close loopholes. This ensures skill documentation effectively guides agent behavior. It also provides best practices for skill naming, directory structure, description optimization (Skill Discovery Optimization), and cross-skill referencing.
