Superpowers is a plugin system that equips Claude Code and other AI agents with composable "skills" — structured instructions that enforce disciplined software development practices.

• Created by Jesse Vincent at Prime Radiant
• MIT licensed, fully open source
• 14 composable skills in the core library
• Available on Claude Code marketplace (Jan 2026)

# Repo structure
skills/          # 14 skill definitions
agents/          # Subagent configs
commands/        # CLI commands
docs/            # Platform docs
hooks/           # Integration hooks

Skills are not always loaded. The AI agent searches skill descriptions when it encounters a relevant situation, deciding in real-time which skills to read.

Anti-pattern

# BAD: summarizes workflow
description: Guides the agent through
  red-green-refactor TDD cycles

# GOOD: states trigger condition
description: Use when implementing any
  feature or bugfix, before writing
  implementation code

Keyword Strategy

• Error messages the agent might search for
• Symptoms: "flaky", "hanging", "race condition"
• Tool names and library references
• Synonyms for common problems

Size Constraints

Token-efficient by design. Cross-reference other skills rather than repeating content.

The terminal state is always invoking writing-plans. No other exit path allowed.

Why Worktrees?

Standard branches require switching context and losing state. Worktrees create parallel directories on separate branches — the main workspace stays untouched.

Directory Priority

• 1. Check for existing .worktrees/ directory
• 2. Consult CLAUDE.md for preferences
• 3. Ask the user if neither exists

Safety Verification

# MUST verify before creating
git check-ignore .worktrees/

# If NOT ignored, add first:
echo ".worktrees/" >> .gitignore
git add .gitignore
git commit -m "Ignore worktrees"

# Then create the worktree
git worktree add \
  .worktrees/feature-x -b feature-x

Plan Header

# Feature: User Auth
# Goal: JWT-based login

Architecture:
  Stateless auth with refresh
  token rotation...

Stack: Express, jsonwebtoken, bcrypt
Skills: test-driven-development

Task Format

Each task takes 2-5 minutes and follows TDD:

• Exact file paths (creates, modifications, tests)
• Complete code snippets (not vague descriptions)
• Specific test commands with expected outputs
• Conventional commit messages

Task Example

## Task 3: Password hashing

Files:
  CREATE src/auth/hash.ts
  CREATE tests/auth/hash.test.ts

Test (write first):
  test('hashes password', () => {
    const hash = hashPassword('pw')
    expect(hash).not.toBe('pw')
  })

Run: npm test -- hash
Expected: 1 failing (RED)

Implementation: ...
Commit: "feat(auth): add hash"

Why Fresh Agents?

Long conversations degrade AI output quality. Fresh agents have no context pollution from previous tasks — each operates at peak capability.

Status Protocol

Never force retries without addressing the underlying issue.

RED

Write a minimal failing test that captures one requirement. Run it. Confirm it fails for the right reason.

GREEN

Write the simplest possible code to make the test pass. Nothing more. Verify no regressions.

REFACTOR

Clean up while keeping tests green. Improve design without changing behavior. Commit.

Common Rationalizations (Countered)

The skill includes 12 rationalizations with counters — each discovered through real AI agent testing.

Code Review Process

• Spec compliance review comes first — does it match requirements?
• Code quality review comes second — is it well-built?
• Order matters: quality fixes must not violate spec
• Issues reported by severity level
• Implementer fixes, reviewer re-checks

Branch Completion

• All tests verified passing
• Merge or PR options presented
• Workspace cleaned up
• Summary of changes generated

Model Selection Strategy

Reserve capability for complexity. Don't waste expensive models on boilerplate.

RED Phase

Create pressure scenarios. Run subagents without the skill. Document exactly how they fail:

• What choices agents make
• Verbatim rationalizations they offer
• Which pressures trigger violations

GREEN Phase

Write minimal skill addressing only those specific failures. Run scenarios again — agents should now comply.

REFACTOR Phase

Agents find new rationalizations. Add explicit counters for each loophole. Build rationalization tables. Re-test until bulletproof.

# Skill file structure
skills/
  my-skill/
    SKILL.md       # Required
    reference.*    # Optional heavy ref

# SKILL.md anatomy
---
name: my-skill-name
description: Use when [trigger]
---
# Overview     1-2 sentences
# When to Use  symptom bullets
# Core Pattern before/after
# Quick Ref    scannable table
# Mistakes     errors + fixes
# Red Flags    self-check list

AI agents are excellent rationalizers. Given any rule, they'll find creative justifications for violating it. Superpowers treats this as a first-class engineering problem.

Techniques

• Close every loophole explicitly — don't just state the rule; forbid specific workarounds
• Address spirit vs. letter — add foundational principles that cut off entire categories
• Red flags checklist — help agents self-check when tempted
• Rationalization tables — map every excuse to a counter-argument

Example: TDD Skill

# Common Rationalizations table

| Excuse | Reality |
"It's trivial"
  -> Trivial code gets complex fast

"I'll add tests after"
  -> Tests-after can't prove causation

"Just exploring"
  -> Exploration code becomes prod

# Red Flags
[ ] Writing code before tests
[ ] Tests that can't fail
[ ] Skipping the RED verify step
[ ] Multiple features per cycle

Notice how Phase 4 feeds back into the TDD skill — skills are composable. Debugging's fix phase triggers TDD's red-green-refactor cycle.

AI agents have a dangerous tendency to declare success prematurely. This skill enforces evidence-based completion.

• All tests must actually pass (not "should pass")
• The agent must run the tests, not just claim it did
• Output must be verified against expectations
• Edge cases must be explicitly tested
• No "I'm confident this works" without proof

Verification Checklist

# Before declaring DONE:

[ ] Tests exist for all new code
[ ] Test suite actually executed
[ ] All tests pass (screenshot/log)
[ ] No regressions in existing tests
[ ] Edge cases covered
[ ] Error handling verified
[ ] Changes match spec exactly
[ ] Commit message is conventional

# If ANY box unchecked:
Status: NOT DONE
# Fix, re-run, re-verify.

Repo Language Mix

Shell       57.8%  ||||||||||||
JavaScript  30.1%  ||||||
HTML         5.2%  |
Python       3.8%  |
TypeScript   2.3%  |

Primarily Shell + markdown. Skills are just text files — no compilation, no runtime, no dependencies. The "code" is the methodology itself.

This is a key architectural choice: skills work with any AI agent that can read markdown, making the framework inherently portable.

This is the endgame: you brainstorm, approve a design, approve a plan, then walk away. The agent executes tasks via subagents, reviews each one, fixes issues, and commits — all without human intervention.

What Makes It Possible

• Detailed plans remove ambiguity
• Fresh subagents prevent context drift
• Two-stage review catches errors
• TDD enforcement ensures correctness
• Status protocol handles blockers

# You type:
"I need user authentication"

# Agent responds (Phase 1):
Q1: What type of auth?
  a) Username/password
  b) OAuth (Google, GitHub)
  c) Magic link (email)
  d) All of the above

# You pick: a + b

Q2: Session management?
  a) JWT (stateless)
  b) Server-side sessions
  c) JWT + refresh tokens

# You pick: c

Q3: Need role-based access?
  a) No, just authenticated/not
  b) Yes, admin + user
  c) Yes, custom roles

# Agent then presents design...

What's Happening

• One question per message (prevents overload)
• Multiple choice where possible (faster decisions)
• Each question narrows scope
• Agent never assumes an answer

Design Pattern

Skills don't embed other skills' content. Instead, they cross-reference — "invoke the writing-plans skill" rather than duplicating planning logic.

• Keeps each skill under 500 words
• Prevents inconsistency from duplication
• Skills can be updated independently
• New skills can plug into existing chains

Why It Went Viral

• Solves real pain — everyone using AI coding hit the same walls
• Zero friction — marketplace install, works immediately
• Visible results — before/after difference is obvious
• Open source — MIT license, no lock-in
• Platform agnostic — not tied to one tool
• Extensible — write your own skills

Superpowers has no runtime. No compilation. No framework code. The entire system is markdown files that AI agents read and follow.

This is intentional

• Portable — any AI that reads markdown works
• Inspectable — you can read every skill in plain English
• Forkable — customize by editing text, not code
• Debuggable — when the agent misbehaves, read what it was told
• Versionable — standard git workflows for skill evolution

The Process

# 1. Create the directory
mkdir skills/my-skill

# 2. Write SKILL.md
---
name: my-deployment-checklist
description: Use when deploying to
  production or staging environments
---

# Overview
Enforce pre-deploy checks...

# When to Use
- Agent mentions "deploy" or "release"
- Changes to CI/CD configuration
- Version bumps

# Core Pattern
...checklist items...

Deployment Checklist

• Pressure test first — run agents without the skill, document failures
• Write minimal skill — address only observed failures
• Test with skill present — confirm it fixes the issues
• Find new rationalizations — add counters
• Re-test until bulletproof