This page describes what Superpowers is, the problem it solves, the platforms it runs on, and the core mechanism by which it enforces structured agent behavior. For installation steps, see Getting Started. For a deeper explanation of individual skills, see Core Concepts.
Superpowers is a skills library and plugin that gives AI coding agents a structured software development workflow. Instead of allowing an agent to jump directly into writing code, Superpowers intercepts the session at startup and loads a set of behavioral guides — called skills — that the agent must consult before acting.
The fundamental insight is that agents are more reliable when given explicit, stepwise processes than when left to improvise. Superpowers encodes proven workflows (TDD, design-before-coding, systematic debugging, subagent-driven development) as skills, and makes checking those skills mandatory rather than optional.
The plugin is maintained at `.claude-plugin/plugin.json`() and currently at version 4.3.1.
Sources: README.md1-15 .claude-plugin/plugin.json1-13
Without Superpowers, a coding agent given "build me a login page" will:
With Superpowers loaded, the same request triggers:
brainstorming skill — forces a design conversation before any code is writtenusing-git-worktrees skill — creates an isolated workspacewriting-plans skill — produces a bite-sized implementation plansubagent-driven-development skill — dispatches reviewers after each tasktest-driven-development skill — enforces RED → GREEN → REFACTOR per taskThis is not a set of suggestions. The using-superpowers meta-skill mandates that if there is even a 1% chance a skill applies, it must be invoked.
Sources: README.md79-94
Superpowers integrates with four AI coding platforms. Each uses a different mechanism to inject skills into the agent's context at session start.
| Platform | Install Method | Integration Mechanism |
|---|---|---|
| Claude Code | Plugin marketplace | SessionStart hook via hooks/hooks.json |
| Cursor | /plugin-add superpowers | .cursor-plugin/plugin.json + additionalContext |
| OpenCode | Manual clone + symlink | experimental.chat.system.transform hook in .opencode/plugins/ |
| Codex | Manual clone + symlink | Native skill discovery via ~/.agents/skills/ |
For per-platform installation instructions, see Getting Started. For implementation details of each integration, see Multi-Platform Integration.
Sources: README.md28-76 .claude-plugin/plugin.json1-13 .cursor-plugin/plugin.json1-18 RELEASE-NOTES.md6-9
The repository has two main concerns: the plugin layer (platform integrations) and the skills layer (behavioral guides).
Plugin layer — lives in obra/superpowers. Contains hooks, platform manifests, shared library code, and test infrastructure.
Skills layer — lives in skills/ within this repo (and was historically in a separate obra/superpowers-skills repo). Contains all SKILL.md files.
Skills-to-platform mapping diagram:
Sources: README.md98-128 .claude-plugin/plugin.json1-13 .cursor-plugin/plugin.json1-18 RELEASE-NOTES.md325-337
Each skill is a SKILL.md file with YAML frontmatter and Markdown content. The frontmatter contains at minimum a name and description field. The description field is the primary trigger mechanism — agents match it against natural language requests without any explicit user command.
Example frontmatter structure (from agents/code-reviewer.md):
---
name: code-reviewer
description: |
Use this agent when a major project step has been completed...
---
Skills are loaded via the Skill tool (Claude Code / Cursor), the native skill tool (OpenCode), or by name-matching during discovery (Codex). The superpowers:skill-name namespace format distinguishes library skills from project-local or personal skills.
For a full explanation of skill types, formats, and invocation, see What Are Skills and Finding and Invoking Skills.
Sources: README.md98-128 agents/code-reviewer.md1-6 RELEASE-NOTES.md383-388
The development workflow Superpowers enforces is a linear pipeline with two human approval gates.
End-to-end workflow:
Each task inside subagent-driven-development or executing-plans follows:
For detailed documentation of each stage, see Complete Workflow Pipeline.
Sources: README.md79-93 RELEASE-NOTES.md218-243
This table maps conceptual components to the concrete files and symbols that implement them.
| Concept | File(s) | Key Symbol |
|---|---|---|
| Plugin manifest (Claude Code) | .claude-plugin/plugin.json | "name": "superpowers" |
| Plugin manifest (Cursor) | .cursor-plugin/plugin.json | "hooks": "./hooks/hooks.json" |
| Session bootstrap (Claude Code/Cursor) | hooks/hooks.json, hooks/session-start | SessionStart event |
| Session bootstrap (OpenCode) | .opencode/plugins/superpowers.js | experimental.chat.system.transform |
| Skill discovery logic | lib/skills-core.js | findSkillsInDir, resolveSkillPath |
| Meta-skill (mandatory protocol) | skills/using-superpowers/SKILL.md | using-superpowers |
| Design workflow | skills/brainstorming/SKILL.md | brainstorming |
| Plan generation | skills/writing-plans/SKILL.md | writing-plans |
| Parallel execution | skills/subagent-driven-development/SKILL.md | subagent-driven-development |
| Test discipline | skills/test-driven-development/SKILL.md | test-driven-development |
| Code reviewer agent | agents/code-reviewer.md | superpowers:code-reviewer |
Sources: README.md98-128 .claude-plugin/plugin.json1-13 .cursor-plugin/plugin.json1-18 RELEASE-NOTES.md325-337
Superpowers is built around four principles stated explicitly in the README:
| Principle | Meaning |
|---|---|
| Test-Driven Development | Write failing tests before any production code |
| Systematic over ad-hoc | Follow a defined process; do not improvise |
| Complexity reduction | YAGNI — do not build what is not asked for |
| Evidence over claims | Verify behavior is correct before reporting success |
These principles are encoded into the skills themselves as hard constraints, not advice. Skills use language like "Iron Law", "HARD-GATE", and explicit Red Flags lists to resist agent rationalization.
Sources: README.md122-128 RELEASE-NOTES.md32-49
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.