Superpowers:
Learn how to use Superpowers, framework skills agents that change coding agents like Claude Code, Cursor, and Codex to be more systematic, tested and religious.
Superpowers: Agentic Framework for Coding Agents That Actually Work
Introduction
Have you ever used an AI coding assistant like Claude Code or Cursor, but got inconsistent results? The code written doesn't match expectations, testing is ignored, or it even makes your project more complicated? You're not alone.
Superpowers comes as the solution. This isn't just a regular plugin—it's an agentic skills framework that changes how coding agents work. Instead of immediately writing code when asked, an agent with Superpowers will:
- Ask first what you actually want to build
- Help create clear specifications
- Create detailed implementation plans
- Execute with strict TDD methodology
- Review its own code before giving it to you
The result? A coding agent that works like a disciplined senior engineer, not a junior who rushes to run code.
Fun fact: Superpowers has 93.9k+ stars on GitHub and has been forked 7.4k+ times. This isn't a small project—this is a proven methodology!
Prerequisites
Before starting, make sure you have:
- Supported coding agent:
- Claude Code (CLI from Anthropic)
- Cursor (AI-powered IDE)
- OpenAI Codex
- OpenCode
- Gemini CLI
- Git installed on your system
- Basic understanding of TDD (Test-Driven Development)
- Project you want to work on
Core Concepts
What are "Skills" in Superpowers?
Think of skills as "work guides" that are automatically activated when the agent detects certain contexts. Similar to a checklist that must be followed before moving to the next stage.
Example: When you ask an agent to "build a new feature", the brainstorming skill will automatically activate and start asking questions about implementation details instead of immediately coding.
Main Superpowers Workflow
[IDEA] → [BRAINSTORMING] → [DESIGN DOC] → [PLAN] → [IMPLEMENT] → [REVIEW] → [FINISH] ↓ ↓ ↓ ↓ ↓ ↓ Questions Validated Tasks TDD Quality Merge/PR & Options Document List Cycle Check Options
Superpowers Philosophy
There are 4 main principles:
- Test-Driven Development - Tests first, always
- Systematic over Ad-hoc - Process, not guessing
- Complexity Reduction - Simplicity as the main goal
- Evidence over Claims - Verify before declaring success
Architecture Overview
┌─────────────────────────────────────────────────────────────────┐ │ SUPERPOWERS FRAMEWORK │ ├─────────────────────────────────────────────────────────────────┤ │ │ │ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │ │ │ PLANNING │ │ CODING │ │ QUALITY │ │ │ │ SKILLS │ │ SKILLS │ │ SKILLS │ │ │ ├─────────────┤ ├─────────────┤ ├─────────────┤ │ │ │ brainstorming│ │ test-driven │ │ requesting- │ │ │ │ writing- │ │ development │ │ code-review │ │ │ │ plans │ │ executing- │ │ systematic- │ │ │ │ using-git- │ │ plans │ │ debugging │ │ │ │ worktrees │ │ subagent- │ │ verification│ │ │ └─────────────┘ │ driven-dev │ │ -before- │ │ │ └─────────────┘ │ completion │ │ │ └─────────────┘ │ │ │ │ ┌─────────────────────────────────────────────────────────┐ │ │ │ META SKILLS │ │ │ │ writing-skills | using-superpowers │ │ │ └─────────────────────────────────────────────────────────┘ │ │ │ └─────────────────────────────────────────────────────────────────┘ │ ▼ ┌─────────────────────────────────────────┐ │ SUPPORTED PLATFORMS │ ├─────────────────────────────────────────┤ │ Claude Code │ Cursor │ Codex │ Gemini │ └─────────────────────────────────────────┘
Step-by-Step: Installing Superpowers
1. Claude Code (Official Marketplace)
The easiest way for Claude Code:
/plugin install superpowers@claude-plugins-official
Or via marketplace:
# Register marketplace first /plugin marketplace add obra/superpowers-marketplace # Install plugin /plugin install superpowers@superpowers-marketplace
2. Cursor IDE
In Cursor Agent chat:
/add-plugin superpowers
Or search for "superpowers" in Cursor's plugin marketplace.
3. OpenAI Codex
Tell Codex:
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.codex/INSTALL.md
4. OpenCode
Same as Codex:
Fetch and follow instructions from https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md
5. Gemini CLI
# Add skill symlink ln -s ~/.codex/superpowers/skills ~/.agents/skills/superpowers
Or add manually to .gemini/settings.json:
{ "skills": { "paths": ["~/.codex/superpowers/skills"] } } ``````bash gemini extensions install https://github.com/obra/superpowers
To update:
gemini extensions update superpowers
Step-by-Step: Using Superpowers
Scenario: Building a New Feature
Let's see a concrete example. Suppose you want to add a "user authentication" feature to your application.
Step 1: Start with a Regular Request
User: Help me add user authentication to my Express.js app
Instead of immediately writing code, an agent with Superpowers will activate the brainstorming skill:
Agent: Before I start coding, I want to understand what you really need. 1. What authentication method do you prefer? (JWT, Session, OAuth?) 2. Do you need social login? (Google, GitHub, etc.) 3. Should users be able to reset passwords? 4. Any specific security requirements?
This is Socratic design refinement—the agent helps you think through details you might have missed.
Step 2: Design Document
After discussion, the agent will create a design document and present it in easy-to-read chunks:
## Authentication Design ### Chosen Approach - JWT-based authentication - Password hashing with bcrypt - Email verification flow ### API Endpoints - POST /auth/register - POST /auth/login - POST /auth/logout - POST /auth/refresh-token ### Security Measures - Rate limiting on login - Secure password storage - Token expiration (15 min access, 7 days refresh)
Step 3: Implementation Plan
After you approve the design, the writing-plans skill activates:
## Implementation Plan ### Task 1: Setup Dependencies - Install jsonwebtoken, bcryptjs - Add types for TypeScript - **Verification**: npm install succeeds, types resolve ### Task 2: Create User Model - File: src/models/User.ts - Fields: email, passwordHash, verified, createdAt - **Verification**: TypeScript compiles ### Task 3: Write Auth Service Tests - File: src/services/auth.test.ts - Test cases: register, login, token refresh - **Verification**: Tests FAIL (expected, TDD!) ### Task 4: Implement Auth Service - File: src/services/auth.ts - Implement all methods - **Verification**: Tests PASS [... and so on]
Notice: each task has a clear verification step.
Step 4: Subagent-Driven Development
When you say "go", the subagent-driven-development skill activates:
- Spawn subagent for Task 1
- Review results (spec compliance + code quality)
- If OK, proceed to Task 2
- If issues, fix first
The agent can work 2+ hours autonomously without deviating from the plan!
Step 5: Code Review
Between tasks, the requesting-code-review skill automatically activates:
## Code Review Report ### Task 3: Auth Service Tests ✅ Spec Compliance: All test cases match design ✅ Code Quality: Good coverage (95%) ### Issues Found: - ⚠️ Minor: Missing edge case for empty email - ⚠️ Minor: Should test concurrent login attempts ### Verdict: PASS with minor fixes
Step 6: Finishing Branch
After all tasks are complete, the finishing-a-development-branch skill activates:
All tasks completed! Tests passing. Here are your options: 1. Merge to main 2. Create Pull Request 3. Keep branch for review 4. Discard changes What would you like to do?
Deep Dive: Key Skills
Test-Driven Development (TDD)
Superpowers enforces the RED-GREEN-REFACTOR cycle:
// Step 1: RED - Write failing test describe('AuthService', () => { it('should register new user', async () => { const result = await auth.register({ email: 'test@example.com', password: 'SecurePass123!' }); expect(result.success).toBe(true); }); }); // Run test → FAILS (function doesn't exist yet) // Step 2: GREEN - Write minimal code to pass async function register(user) { return { success: true }; } // Run test → PASSES // Step 3: REFACTOR - Improve code quality async function register(user) { // Validate input if (!user.email || !user.password) { throw new Error('Missing fields'); } // Hash password const hashedPassword = await bcrypt.hash(user.password, 10); // Save to database const newUser = await User.create({ email: user.email, passwordHash: hashedPassword }); return { success: true, user: newUser }; } // Tests still pass → Refactoring successful!
Git Worktrees for Isolation
Superpowers uses git worktrees for safe parallel development:
# Create isolated worktree for feature git worktree add ../my-feature-auth feature/auth # Agent works in isolated directory cd ../my-feature-auth # Can test independently without affecting main npm test # When done, merge back cd ../main-project git worktree remove ../my-feature-auth
Benefits:
- Multiple features in parallel without conflicts
- Clean rollback if something goes wrong
- Main branch stays stable
Verification Before Completion
Every task must pass verification:
## Verification Checklist ### Task: User Registration - [ ] Unit tests pass - [ ] Integration tests pass - [ ] TypeScript compiles without errors - [ ] No linting errors - [ ] Manual test: user can register - [ ] Manual test: duplicate email rejected
This prevents agents from claiming "done" when work isn't actually complete.Anti-patterns to avoid:
- Writing code before tests
- Skipping tests because "I'm sure"
- Tests that aren't independent
Systematic Debugging
When there's a bug, the systematic-debugging skill activates with a 4-phase process:
Phase 1: REPRODUCE - Document exact steps to trigger bug - Verify it's not environment-specific Phase 2: ISOLATE - Binary search the codebase - Create minimal reproduction case Phase 3: ROOT CAUSE - Trace the execution flow - Identify exact point of failure Phase 4: FIX & VERIFY - Implement fix - Add regression test - Verify fix works - Check no side effects
Git Worktrees for Parallel Development
The using-git-worktrees skill allows you to work on multiple features simultaneously:
# Main repo: /project # Feature A: /project/.worktrees/feature-auth # Feature B: /project/.worktrees/feature-api # Each has its own separate branch # No conflicts between development streams
Best Practices
1. Let the Agent Ask Questions
Don't answer with "just code it". The more detailed the brainstorming, the better the results.
2. Review Design Documents
Take time to read the design doc. It's easier to correct at this stage than after code is written.
3. Trust the Process
TDD might feel slow at first, but bugs prevented during development are cheaper than bugs in production.
4. Regular Checkpoints
For large projects, use executing-plans with checkpoints:
"Execute the plan with checkpoints after every 5 tasks"
5. Custom Skills
You can create your own skills! See skills/writing-skills/SKILL.md in the Superpowers repo.
Common Mistakes
❌ Mistake 1: Skip Brainstorming
User: Just implement authentication, don't ask questions
Result: Code that doesn't match requirements, needs rewrite.
Solution: Always follow the brainstorming process.
❌ Mistake 2: Ignore Test Failures
Agent: Test failed. Should I fix it? User: Skip for now, I'll fix later
Result: Technical debt that keeps piling up.
Solution: Always fix test failures before proceeding.
❌ Mistake 3: Not Reading the Plan
Agent: Here's the implementation plan [long document] User: Looks good, go ahead
Result: Surprises when results don't match expectations.
Solution: Read the plan in detail. Request changes if needed.
❌ Mistake 4: Working on Main Branch
User: Let's implement this directly on main
Result: No rollback path if problems occur.
Solution: Use worktrees or at least a separate branch.
Advanced Tips
Parallel Agent Dispatch
For independent tasks, use the dispatching-parallel-agents skill:
"Implement tasks 1-5 in parallel with separate subagents"
This leverages parallel processing to speed up development.
Custom Skill Creation
Create skills for patterns you frequently use:
# skills/my-custom-pattern/SKILL.md ## Trigger When user asks to implement a new API endpoint ## Steps 1. Check if route exists 2. Validate request schema 3. Write integration test 4. Implement handler 5. Add API documentation
CI/CD Integration
Superpowers can be integrated with CI pipelines:
# .github/workflows/superpowers-check.yml name: Superpowers Quality Check on: [pull_request] jobs: review: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - name: Run Superpowers Review run: | # Agent will perform automatic code review # with Superpowers standards
Summary & Next Steps
Key Takeaways
- Superpowers = Framework + Methodology - Not just a plugin, but a new way of working
- Skills Auto-Activate - Agent knows when to use which skill
- TDD is Mandatory - No exceptions, always test first
- Quality Gates - Every step has verification
- Parallel Development - Worktrees enable safe parallel work
Recommended Learning Path
| Level | Focus |
|---|---|
| Beginner | Install Superpowers, try brainstorming skill |
| Intermediate | Understand TDD flow, use worktrees |
| Advanced | Create custom skills, parallel agents |
| Expert | CI/CD integration, team-wide adoption |
Resources
Conclusion
Superpowers isn't a magic wand that makes all code perfect. It's a framework that forces discipline and process in AI-assisted software development.
The main benefit isn't speed—it's consistency and quality. Agents with Superpowers produce code that:
- Matches specifications
- Has good test coverage
- Follows best practices
- Is easy to review and maintain
In 2026, where AI coding agents are becoming the norm, the difference between "coding with AI" and "professional software development with AI" is the methodology used. Superpowers bridges that gap.
Ready to give your coding agent superpowers? 🦸♂️