Superpowers Framework: Building Reliable AI Coding Agents with Composable Skills

TL;DR

Superpowers is an open-source framework by Jesse Vincent (GitHub: obra) — a methodology for building AI coding agents using composable skills that auto-trigger. Instead of writing prompt chains manually, you define skills and the agent decides autonomously when to use each one. Supports Claude Code (Marketplace), Cursor, Codex, OpenCode, and Gemini CLI.

When you build an AI coding agent ad-hoc — a few prompt chains, some system messages — it often works for small projects. But as complexity grows, problems emerge: the agent doesn't know when to plan vs code, when to test vs ship. There are no clear boundaries.

Superpowers addresses this by asking the foundational question: If an agent must follow a professional software workflow, what does that workflow actually look like?

What is Superpowers?

From the GitHub repo (author Jesse Vincent):

"Superpowers is a complete software development workflow for your coding agents, built on top of a set of composable 'skills' and some initial instructions that make sure your agent uses them."

The framework has two parts:

1. Skills library — a collection of skills as SKILL.md files, each with a name, description, and specific instructions
2. Initial instructions — directs the agent to check skills before starting any task

The agent doesn't need to be told "use skill X." It self-checks the skills library before each task and selects the appropriate skill.

Superpowers: modular skill blocks connecting into a complete agent workflow

Basic Workflow — 7 Steps

Superpowers defines a 7-step workflow that agents must follow — mandatory workflows, not suggestions:

1. brainstorming

Triggers before writing any code. Refines rough ideas through Socratic questioning, explores alternatives, presents design in digestible sections for validation. Saves a design document.

2. using-git-worktrees

Triggers after design approval. Creates an isolated workspace on a new branch, runs project setup, verifies a clean test baseline — before any code is written.

3. writing-plans

Triggers with the approved design. Breaks work into bite-sized tasks (2-5 minutes each). Every task includes:

• Exact file paths
• Complete code to write
• Verification steps

4. subagent-driven-development

Triggers with the plan. Dispatches a fresh subagent per task with two-stage review:

1. Spec compliance check
2. Code quality check

5. test-driven-development

Triggers throughout implementation. Mandatory RED-GREEN-REFACTOR: write failing test → watch it fail → write minimal code → watch it pass → commit. Deletes code written before tests (this is enforced).

6. requesting-code-review

Triggers between tasks. Reviews against the plan, reports issues by severity. Critical issues block progress — the agent doesn't move forward until they're resolved.

7. finishing-a-development-branch

Triggers when all tasks complete. Verifies tests, presents options (merge/PR/keep/discard), cleans up worktree.

Composable Skills Library

Full list of skills included in Superpowers (from the GitHub README):

Testing:

• test-driven-development — RED-GREEN-REFACTOR cycle (includes testing anti-patterns reference)

Debugging:

• systematic-debugging — 4-phase root cause process (root-cause-tracing, defense-in-depth, condition-based-waiting)
• verification-before-completion — Ensures tasks are genuinely complete before marking done

Collaboration:

• brainstorming — Socratic design refinement
• writing-plans — Detailed implementation plans
• executing-plans — Batch execution with human checkpoints
• dispatching-parallel-agents — Concurrent subagent workflows
• requesting-code-review — Pre-review checklist
• receiving-code-review — Responding to feedback
• using-git-worktrees — Parallel development branches
• finishing-a-development-branch — Merge/PR decision workflow
• subagent-driven-development — Fast iteration with two-stage review

Meta:

• writing-skills — Create new skills following best practices
• using-superpowers — Introduction to the skills system

The Power of Composability

Why composable skills outperform prompt chains:

Prompt chains:

• Hard-coded execution order
• Difficult to reuse across projects
• No automatic skill discovery
• Each chain is a large context blob

Composable skills:

• Modular — add or remove skills independently
• Reusable — same skill library across all projects
• Auto-discovery — agent checks skills before acting
• Testable — each skill has a clear I/O contract

The critical point: the agent doesn't need manual reminders. Skills trigger automatically based on context.

Installation

Superpowers supports multiple platforms:

Claude Code (easiest):

• Install via Claude Code Official Marketplace or Plugin Marketplace directly

Cursor:

• Install via the Plugin Marketplace

Codex and OpenCode:

• Requires manual setup (see README for instructions)

Gemini CLI:

• Supported with platform-specific setup in the README

After install, verify:

# Ask the agent about available skills
"What superpowers do you have available?"

Superpowers vs gstack

Both launched in the same week (March 2026) and address similar problems — through different approaches:

When to Use Superpowers

Good fit:

• Teams that want a consistent agent development methodology, not just tooling
• Projects requiring strict TDD from the start
• Developers using multiple coding agents (Claude, Cursor, Gemini CLI) who want the same framework across all
• Teams who want to extend the framework with custom skills

Less useful if:

• You need integrated browser automation or QA testing → consider gstack
• Project scope is small and doesn't warrant a structured workflow

Writing Custom Skills

Superpowers includes a writing-skills skill that teaches you to create new skills:

# Skill name
---
name: my-custom-skill
description: Short description so the agent knows when to use this
---

## When to use this skill
[Trigger conditions]

## Instructions
[Step-by-step instructions]

Skill files follow the same SKILL.md format — they can be shared with the community or kept private in your repo.

The Bigger Picture: From Generic Agents to Structured Methodology

Superpowers and gstack reflect a larger shift: the developer community is recognizing that good agentic workflows need structure, not just capable models.

When you hand an agent a complex task without a workflow, it doesn't know when to plan, when to code, when to test. The outcome is often disorganized.

Superpowers lays a methodology foundation — similar to how Agile or TDD provides structure for human developers — and applies it directly to agent behavior.

FAQ

Is Superpowers free? Yes — open source, no pricing plans. You only need a subscription for the platform you're using (Claude Code, Cursor, etc.).

Do skills trigger automatically or do I have to call them manually? Skills trigger automatically — the agent checks the skills library before acting and selects the appropriate skill based on context. This is the key difference from manual slash commands.

Does Superpowers work with Gemini CLI? Yes — the README lists Gemini CLI as a supported platform with platform-specific instructions.

Can I write custom skills? Yes — writing-skills is a skill that teaches you how to create new skills following the framework's format and best practices.