Superpowers — The Minimum Meta-Framework Before You Can Claim You "Really Use Claude Code"

TL;DR

• Superpowers is a Claude Code meta-skill framework by Jesse Vincent (obra) — not a single skill bundle, but a package of 14 skills + a SessionStart bootstrap that holds an opinion about the agent's way of working itself.
• Three main functions:
  1. Automatic bootstrap injection — a SessionStart hook injects using-superpowers into context at the start of every session, laying the 1% rule, the HARD-GATEs, and the priority order (user instruction > skill) above the system prompt.
  2. Automatic work-pipeline triggers — a single "build me X" self-invokes brainstorming → writing-plans → subagent-driven-development → requesting-code-review. The user never has to call skills one by one.
  3. Always-on quality discipline — test-driven-development's RED-GREEN-REFACTOR, systematic-debugging's Iron Law, and verification-before-completion stay on at all times, blocking "patch without a test," "work around it without a root cause," and "declare done without verifying."
• It's plenty strong on its own. Mix it with other meta-frameworks, custom slashes, or quick one-off tasks and conflicts arise — see the 7 patterns and their fixes in §4 to steer clear. 95% of them are solved by a single page of AGENTS.md/CLAUDE.md.

1. Introducing Superpowers

1.1. What it is

obra/superpowers — a Claude Code meta-skill plugin by Jesse Vincent (obra). The README introduces it as "a complete software development methodology for your coding agents, built on top of a set of composable skills" — less a skill bundle than a framework with an opinion about how the agent writes code itself. It's made of 14 skills + a SessionStart bootstrap hook, and the same bootstrap is forked to land in Codex CLI, Cursor, Gemini CLI, and Copilot CLI as well as Claude Code.

1.2. Strengths

• Skill invocation is automated. A single "build me X" self-invokes brainstorming → writing-plans → subagent-driven-development → requesting-code-review in order. No need to type slashes one by one.
• Quality discipline is always on. TDD (RED-GREEN-REFACTOR), systematic-debugging's Iron Law (no patching without a root cause), and verification-before-completion (real verification before declaring done) run by default throughout code work.
• Behavior stays consistent across harnesses. Not just Claude Code but Cursor, Copilot CLI, and the rest get the same using-superpowers message in the first context, keeping priorities and discipline uniform.
• A guide to writing meta-skills ships with it. writing-skills lays down best practices grounded in Cialdini/Meincke persuasion principles — directly reusable when you add your own skills.

1.3. Installation

One line via the official Claude Code marketplace.

/plugin install superpowers@claude-plugins-official

Or add obra's own marketplace directly.

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Start a new session after installing and the SessionStart hook runs automatically, injecting using-superpowers/SKILL.md into the first context — the 1% rule and the HARD-GATEs turn on immediately with no extra config.

2. How it works — hook → bootstrap → lazy load

2.1. The SessionStart hook as the entry point

The SessionStart matcher in the plugin root's hooks/hooks.json is startup|clear|compact. In other words, on every new session, /clear, and right after auto-compaction, the bootstrap script runs.

The session-start script reads skills/using-superpowers/SKILL.md whole, JSON-escapes it, and injects it into context — forking to hookSpecificOutput.additionalContext for Claude Code, additional_context for Cursor, and additionalContext for Copilot CLI. The guarantee that the same message lands in the first context no matter the harness is the core design decision.

2.2. The using-superpowers skill lays the behavioral rules

The injected using-superpowers/SKILL.md is a short 117-line bootstrap, but it nails down three things:

• The 1% rule — if there's even a 1% chance a skill applies, you must invoke it. A rationalization guard that blocks "this is too simple to bother with."
• Imperative tone — "YOU MUST," "Not negotiable," "No exceptions." This is intentional design, codified in writing-skills/persuasion-principles.md as the Authority principle (citing the 7 persuasion principles of Meincke et al. 2025, N=28k conversations — a 33% → 72% compliance gain).
• User first — CLAUDE.md, AGENTS.md, and direct in-conversation instructions take priority over skills. This isn't a rule Anthropic set; it's a priority obra explicitly laid down.

2.3. The 14 SKILL.md files load lazily

The bootstrap keeps only the list in context; the actual SKILL.md bodies load when the Skill tool invokes them. All 14 skills total 3,207 lines, but only the 117-line bootstrap enters at session start. It's a design that consciously cuts context cost.

The invocation trigger splits two ways:

1. Model self-invocation — the model calls a skill on its own via description matching (brainstorming description: "You MUST use this before any creative work").
2. User-explicit — a /skill-name slash command. But v5.1.0 removed legacy slashes like /brainstorm, /execute-plan, and /write-plan, so officially, self-invocation is the default path.

3. The 14-skill catalog

The 5 most-used skills

The five you effectively hit every cycle of work.

brainstorming (164 lines, process gate)

The HARD-GATE that triggers first when a new-feature or behavior-change utterance comes in. It makes you agree on intent, requirements, and design with the user before writing code. The SKILL.md nails the door shut — "Every project goes through this process. A todo list, a single-function utility, a config change — all of them" — sealing off exceptions. Most of the conflicts in this piece start here.

writing-plans (152 lines, process gate)

Converts the design agreed in brainstorming into an actionable implementation plan. It produces a permanent artifact that can be carried into a separate context for work spanning multiple sessions. It hands off to subagent-driven-development (recommended) or, as a fallback, executing-plans.

subagent-driven-development (279 lines, process gate)

Distributed subagent execution of the plan within one session + two-stage review. The recommended path that executing-plans/SKILL.md explicitly points to ("go that way if SDD is possible"). It keeps the main context clean and reviews results task by task.

test-driven-development (371 lines, quality discipline)

Forces RED-GREEN-REFACTOR on new-feature and bugfix work. Always on by default during code work, with "delete code written without a test" as the baseline. Mis-match it onto non-code work (docs, config, etc.) and you get the friction in §4.5.

systematic-debugging (296 lines, quality discipline)

Enforces the Iron Law (no patching without a root cause) on bugs and test failures. A heavy skill accompanied by 11 auxiliary files, it guides the hypothesis → experiment → verification procedure step by step.

4. Where it breaks when mixed with other skills or custom procedures

The points below aren't from hitting these conflicts in practice — they're deduced from Superpowers' hooks and SKILL.md definitions, marking where a collision is unavoidable.

4.1. brainstorming HARD-GATE vs custom procedure commands

The most common one. Even on a homemade slash command that clearly means "run this procedure" (e.g., a daily info-gathering routine, a periodic report generator), the brainstorming description ("You MUST use this before any creative work") matches, and a design step like "what should we build today?" pops up first.

Why it breaks: the HARD-GATE is deliberately strong. brainstorming/SKILL.md nails down "Every project goes through this process. A todo list, a single-function utility, a config change — all of them." "No exceptions" is the guard's whole purpose.

Fix:

1. At the top of the project AGENTS.md or CLAUDE.md, state: "Every slash command in this directory is already past design. Do not invoke the brainstorming skill."
2. Drop one line into the body of the custom slash command (.claude/commands/<name>.md): "This command runs an already-agreed procedure. Disable the brainstorming skill."
3. Have the user explicitly say "skip brainstorming" when starting. Cleaner still if there's a toggle like an MVP mode in PROFILE.md.

4.2. The 1% rule + friction on MVP/one-off tasks

"Just fix this one line" goes through a full skill-check round every time. The 1% rule's Red Flags table classifies thoughts like "This is just a simple question" as rationalization. In other words, simplicity is no grounds for skipping.

Why it breaks: the design barely considers the case where the offender is the user, not the model itself. obra's intent is "keep the agent from being lazy," but the flip side is the case where "the agent is so diligent" that the user feels friction.

Fix: declare a skill-agnostic mode. Put a clause in PROFILE.md like "if the user declares 'skip brainstorming' etc. → it's OK to override the user's earlier decision" (this site's PROFILE is set up that way). Because the bootstrap codifies user instruction as taking priority over skills, this toggle works.

4.3. SessionStart hook duplication (when other meta-frameworks are installed at once)

addyosmani/agent-skills and obra/superpowers both register a SessionStart hook via hooks/hooks.json — install both and the bootstrap message is injected twice (obra's using-superpowers, addyosmani's own meta-skill context). When two similar-but-different priority tables get laid down, the model wavers over which to follow.

mattpocock/skills is a different case. Here the .claude-plugin/plugin.json holds only a skill manifest and there's no SessionStart hook — it just drops markdown into ~/.claude/skills/, so no hook duplication occurs. The separate issue here is skill-name collision (e.g., caveman, tdd possibly clashing with superpowers' same-named skills).

Why it breaks: a SessionStart hook appends a message to the global context. When two frameworks inject different tones and different priority declarations at once, they collide directly (see obra's known double-injection bug at obra/superpowers#648).

Fix: only one meta-framework with a bootstrap hook. Keep obra/superpowers as the base and don't co-install another meta-framework that lays down its own SessionStart, like addyosmani's. A mattpocock-style hookless skill collection is fine to import together at the .claude/skills level, but check ahead of time for overlapping skill names.

4.4. AGENTS.md priority only works when a policy file exists

The bootstrap nails down "explicit user instruction > skill," but if there's no CLAUDE.md/AGENTS.md/GEMINI.md at all, the arbiter disappears. The model then leans conservatively toward skill-first.

Why it breaks: the priority table works "when the user has specified something." An empty project has nothing specified, so the table is useless.

Fix: keep a policy file, however thin. Even a one-line AGENTS.md in the directory ("This project runs in MVP mode. Skip the brainstorming and planning phases") makes the priority table work. The emptier the project, the more it's needed.

4.5. The TDD skill + non-code work

test-driven-development/SKILL.md lists "Always: New features, Bug fixes" as forced scenarios. But on non-code work (config changes, doc edits, markdown writing), if action keywords ("fix," "add," "implement") creep in, TDD triggers.

Why it breaks: a skill description's self-match is semantic, but when a task utterance's vocabulary overlaps with the description's trigger words ("New features, Bug fixes"), the model under-weighs the contextual difference.

Fix: consciously avoid the keywords in your utterance ("rephrase," "reword" over "update," "rewrite"). Or state in one line at the start that "this isn't a code change." The latter is more stable.

4.6. dispatching-parallel-agents auto-dispatch vs single-context tracking

Description: "Use when facing 2+ independent tasks that can be worked on without shared state." The intent is good, but work like "security review + migration + data transformation" — which you deliberately want in one context because decision-tracking matters — also matches.

Why it breaks: the "independent means parallel" rule is too general to catch the user's intent ("these need to be tracked together").

Fix: state in one line at the start that "this is work to track together in one context." Or, for projects where decision-tracking matters (security, finance, healthcare), state "disable parallel dispatch" in the AGENTS.md.

4.7. The weight of writing-skills

It's a 655-line meta-skill. Say "make me one skill" and it triggers a pressure-scenario plus a subagent-verification routine. Legitimate design, but overkill for cases where one skill is fine as a page of markdown.

Why it breaks: writing-skills treats a skill as a document that forces behavior. The rule its body nails down is "Iron Law: No skill without failing test first" (writing-skills/SKILL.md:651) — it demands a RED-GREEN matrix that directly verifies, via a subagent, both the baseline where the agent breaks the rule without the skill (RED) and the compliance once the skill is applied (GREEN). It doesn't fit a skill at the level of a simple memo.

Fix: state "this skill is a lightweight memo, so skip the pressure-scenario verification" and write it simply. Or put the .md in .claude/commands/ rather than ~/.claude/skills/, where it's handled as a slash command and writing-skills' pressure doesn't apply.

5. Synthesis — Superpowers is a framework of "strong opinions"

In three lines:

1. It's not a single skill set. It's an agent-behavior framework made of a SessionStart hook + bootstrap + 14 lazy-loaded skills.
2. A strong priority design. Persuasion principles like Authority, Commitment, and Social proof are consciously embedded in the SKILL.md bodies (see writing-skills/persuasion-principles.md). Design, not accident.
3. The source of friction comes from that opinion, too. The brainstorming HARD-GATE, the 1% rule, forced TDD — all intentional design, but they collide every time the work context doesn't fit. Stating the priorities in AGENTS.md/CLAUDE.md solves 95% of the conflicts.

Operational takeaway: lay Superpowers as the base, and add domain skills and custom slash commands individually under .claude/skills or .claude/commands. Don't co-install a second meta-framework. Lay down a one-page AGENTS.md of priority guardrails and most of the friction disappears.

References

• obra/superpowers — at v5.1.0
• Superpowers RELEASE-NOTES.md — 2026-04-30 v5.1.0 changes (legacy slashes removed, worktree skill rewritten, code review consolidated)
• writing-skills/persuasion-principles.md — applied guide to the 7 persuasion principles from Meincke et al. (2025)
• Agent Skills guide (addyosmani) — the position of a meta-framework used here for comparison