Claude Superpowers Skill Guide (2026)
Ten things you can actually do with obra’s Superpowers — brainstorm a spec, write a task-gated plan, implement with red-green TDD, fan work out to parallel agents, debug by hypothesis, and gate a merge with a reviewer subagent — each as a single Claude Code prompt with the artifact it produces.
Already know what skills are? Skip to the cookbook. First time? Read the explainer first. Deciding whether to adopt it at all? That’s a different question — see Is Superpowers still worth it in 2026? This post is the how-to.
On this page · 21 sections▾
- What this skill does
- The cookbook
- Install + README
- Watch it built
- 01 · Brainstorm a feature before any code (the gate)
- 02 · Write an implementation plan a stranger could execute
- 03 · Implement with red-green-refactor TDD (no code without a failing test)
- 04 · Run multiple tasks in parallel with subagents
- 05 · Isolate the work in a git worktree first
- 06 · Debug a flaky failure systematically (not by guessing)
- 07 · Verify the work is actually done before claiming it
- 08 · Request a structured code review from a fresh subagent
- 09 · Finish the branch cleanly (merge, tag, tear down)
- 10 · Author your own composable skill (extend the framework)
- Community signal
- The contrarian take
- Real workflows shipped
- Gotchas
- Pairs well with
- FAQ
- Sources
What this skill actually does
Sixty seconds of context before the cookbook — what the using-superpowers anchor skill is, what Claude does when you invoke it, and the one thing it does NOT do for you. Superpowers is obra’s (Jesse Vincent’s) framework of composable skills; this anchor is the piece that makes the agent actually run them.
What this skill actually does
“Use when starting any conversation - establishes mandatory workflows for finding and using skills, including using Skill tool before announcing usage and following brainstorming before coding.”
— obra (Jesse Vincent), the skill author · /skills/using-superpowers
What Claude returns
Invoking using-superpowers loads the anchor that makes Claude actually run the rest of the Superpowers skills. It establishes an instruction hierarchy (your explicit instructions > Superpowers skills > default behavior) and a hard rule: if there's even a 1% chance a skill applies, the agent must invoke it via the Skill tool before responding — even before asking clarifying questions. From there the composable sub-skills take over: brainstorming writes a design spec to docs/superpowers/specs/, writing-plans turns it into a task-gated plan in docs/superpowers/plans/, test-driven-development enforces red-green-refactor, and requesting-code-review dispatches a diff-scoped reviewer subagent. Checklists are tracked with TodoWrite.
What it does NOT do
It is not a silver bullet and it is not free — the gated brainstorm/plan/review loop is token-hungry by design and is overkill for a quick one-file fix. It also does not install the other Superpowers skills for you; using-superpowers is the anchor, but each sub-skill must be present in your skills directory to be invoked.
How you trigger it
Use the Superpowers workflow — brainstorm this feature with me before writing any code.Follow brainstorming, then writing-plans, then implement with TDD.Before you say it's done, run verification-before-completion against the spec.Cost when idle
~100 tokens
The cookbook
Each entry below is a workflow you could run this week. They follow Superpowers’ real arc — brainstorm, plan, implement with TDD, parallelise, debug, verify, review, finish — and the last one shows you how to author your own skill. Every entry maps to an actual Superpowers sub-skill and pairs with a skill or MCP server you already have on mcp.directory. You don’t have to run them in order; each is a standalone recipe.
Install + README
If the anchor skill isn’t on your machine yet, here’s the one-liner. The full install panel (Codex, Copilot, Antigravity variants) is on the skill page.
One-line install · by obra
Open skill pageInstall
mkdir -p .claude/skills/using-superpowers && curl -L -o skill.zip "https://mcp.directory/api/skills/download/151" && unzip -o skill.zip -d .claude/skills/using-superpowers && rm skill.zipInstalls to .claude/skills/using-superpowers
Watch it built
A clean end-to-end walkthrough of installing Superpowers and watching the gated loop run — useful before the cookbook because it anchors what each recipe below feels like in the terminal.
Brainstorm a feature before any code (the gate)
Turn a half-formed idea into an approved design spec, one question at a time, before a single line of implementation is written.
ForAnyone starting an ambiguous feature where you don't yet know the shape of the answer. The skill that stops premature coding.
The prompt
Use the using-superpowers workflow to start a brainstorm for a feature: 'add a per-team rate limit to our public API'. Follow the brainstorming skill — ask me one question at a time, prefer multiple-choice, propose 2-3 approaches, and do NOT write any code until I approve the spec. When we're done, write the design spec to docs/superpowers/specs/ and commit it.What slides.md looks like
Skill: brainstorming (engaged before anything else)
Q1 — Where should the limit live?
a) Edge / gateway (before app code runs)
b) Application middleware (per-route)
c) A dedicated rate-limit service
(pick one)
> a
Q2 — What's the bucket key — team, API key, or IP?
...
→ Spec written: docs/superpowers/specs/2026-06-23-api-rate-limit-design.md
→ Committed. Invoking writing-plans next.One-line tweak
Add 'use a visual diagram for the data flow' to the prompt — the brainstorming skill will offer an ASCII or Mermaid sketch before it asks the design questions.
Write an implementation plan a stranger could execute
Convert the approved spec into a phased plan where every task has files, exact commands, code samples, and a test gate — no 'TBD' placeholders.
ForTech leads who want the plan reviewable on its own, and anyone handing work to a subagent or a teammate with zero codebase context.
The prompt
Use the writing-plans skill on docs/superpowers/specs/2026-06-23-api-rate-limit-design.md. Produce a plan where each task is the smallest unit that carries its own test cycle, takes 2-5 minutes, and shows actual code and the exact test command. Include the mandatory header (Goal, Architecture, Tech Stack, Global Constraints with exact values). Save to docs/superpowers/plans/ and run the placeholder scan before you finish.What slides.md looks like
# Plan: Per-team API rate limit
Goal: Reject requests over a team's configured QPS at the gateway.
Architecture: Sliding-window counter in Redis, checked in edge middleware.
Tech Stack: TypeScript, Hono, Upstash Redis
Global Constraints: window=60s, default_limit=600, header=X-RateLimit-*
## Task 1 — Redis sliding-window helper
Files: src/ratelimit/window.ts (produces), src/ratelimit/window.test.ts
[ ] Write failing test for allow()/deny() at the boundary
[ ] Run: pnpm vitest run src/ratelimit/window.test.ts
[ ] Implement, commit
## Task 2 — Edge middleware
...One-line tweak
End the prompt with 'recommend the subagent-driven execution path' to get a plan structured for a fresh agent per task with a review gate between each.
Implement with red-green-refactor TDD (no code without a failing test)
Force the agent to write a failing test, watch it fail, write the minimal code to pass, then refactor — for every task in the plan.
ForAnyone who has watched an agent write confident code with no tests. This is the skill that makes 'it passes' mean something.
The prompt
Execute Task 1 of docs/superpowers/plans/2026-06-23-api-rate-limit.md using the test-driven-development skill. Strict RED-GREEN-REFACTOR: write the failing test first, run it and show me it fails for the right reason, then write the minimal code to pass, run again, then refactor. If you write any production code before a failing test, delete it and start over.What slides.md looks like
RED — wrote window.test.ts:
expect(allow("team-7")).toBe(false) // 601st req in window
$ pnpm vitest run src/ratelimit/window.test.ts
✗ allow() denies over the limit (allow is not defined)
→ Failing for the right reason (no impl yet). Good.
GREEN — minimal impl in window.ts
$ pnpm vitest run ...
✓ 1 passed
REFACTOR — extracted nowSeconds(), tests still green.One-line tweak
Add 'do not stub Redis — use a fakeredis or in-memory adapter so the test exercises real window math' so the GREEN step doesn't pass on a hollow mock.
Run multiple tasks in parallel with subagents
Dispatch independent plan tasks to fresh subagents at once, each with scoped context, so a multi-task plan finishes in one pass instead of serially.
ForEngineers running a large plan where tasks don't depend on each other — migrations across modules, repetitive refactors, fan-out test writing.
The prompt
Use the dispatching-parallel-agents skill to run Tasks 3, 4, and 5 of the plan concurrently. Each subagent gets only the task description and the files it touches — not my full session. Have each one follow the test-driven-development skill, and report back a one-paragraph summary plus the commit SHA. Do not let them edit the same file.What slides.md looks like
Dispatching 3 subagents (scoped context each):
agent-A Task 3: per-key config loader → 4 tests, commit a1b2c3d
agent-B Task 4: X-RateLimit-* headers → 3 tests, commit e4f5g6h
agent-C Task 5: 429 response + Retry-After → 5 tests, commit i7j8k9l
All green. No file overlaps detected.
Next: requesting-code-review on the combined diff.One-line tweak
Pair this with use case 5 (git worktrees) so each parallel agent runs in its own isolated checkout and never trips over another's working tree.
Isolate the work in a git worktree first
Create a clean, gitignored worktree, install deps, and run a baseline test before any feature work starts — so the main checkout never gets contaminated.
ForAnyone running long autonomous sessions or parallel agents, where a half-finished branch in your main tree is a liability.
The prompt
Before we start the rate-limit feature, use the using-git-worktrees skill. Detect whether I'm already in a worktree; if not, create one for branch feat/api-rate-limit, confirm the directory is gitignored, auto-detect this is a pnpm project, install deps, and run the baseline test suite so we know we start from green.What slides.md looks like
Step 0 — not currently in a worktree.
Step 1 — git worktree add ../wt-api-rate-limit feat/api-rate-limit
(../wt-api-rate-limit is gitignored ✓)
Step 2 — detected Node + pnpm → pnpm install
Step 3 — baseline: pnpm vitest run
✓ 142 passed → clean starting state confirmed.
You're isolated. Safe to start implementing.One-line tweak
Drop 'and run the baseline test suite' if your full suite is slow — the worktree still gets created; you just skip the green-baseline confirmation.
Debug a flaky failure systematically (not by guessing)
Force a hypothesis-driven debugging loop — reproduce, isolate, form a single hypothesis, test it — instead of the agent randomly editing lines until the error disappears.
ForAnyone staring at an intermittent CI failure or a bug that 'works on my machine'. Replaces shotgun debugging with a method.
The prompt
A test fails ~1 in 5 runs: src/ratelimit/window.test.ts 'denies at the boundary'. Use the systematic-debugging skill. Reproduce it reliably first (loop the test if needed), then state ONE hypothesis at a time and the experiment that would falsify it. Don't change production code until you've named the root cause out loud.What slides.md looks like
Reproduce: ran test x50 → fails 9/50. Confirmed flaky.
Hypothesis 1: window boundary uses Date.now() ms, test asserts
on whole seconds → off-by-one at the rollover.
Experiment: freeze time at xx:59.997 and assert.
→ Reproduces 100%. Root cause: ms vs s truncation in window().
Fix proposed (after root cause, not before):
floor to seconds in nowSeconds(); add boundary test.One-line tweak
Add 'write the failing reproduction as a permanent regression test before fixing' so the flake can never silently return.
Verify the work is actually done before claiming it
Run an explicit completion checklist — tests pass, the spec's requirements are all met, nothing was stubbed — before the agent says 'done'.
ForAnyone burned by an agent declaring victory while a requirement quietly went unimplemented. The anti-'looks done' skill.
The prompt
Before you tell me the rate-limit feature is complete, run the verification-before-completion skill. Walk the original spec line by line and show me which task or commit satisfies each requirement. Run the full test suite and paste the result. Flag anything stubbed, TODO'd, or skipped. Only then make the completion claim.What slides.md looks like
Verification checklist vs spec:
[✓] per-team limit enforced at edge → Task 2, commit e4f5g6h
[✓] 429 + Retry-After header → Task 5, commit i7j8k9l
[✓] limit configurable per team → Task 3, commit a1b2c3d
[!] metrics emitted to StatsD → NOT DONE (spec §6)
$ pnpm vitest run → ✓ 158 passed
Honest status: 3/4 requirements met. §6 (metrics) still open.One-line tweak
Add 'and run the linter and typecheck, not just tests' so 'verified' covers static checks too, not only the suite.
Request a structured code review from a fresh subagent
Dispatch a reviewer subagent that sees only the diff (not your chat history), grades by severity, and gives a clear proceed-or-fix verdict before merge.
ForSolo developers with no human reviewer, and teams that want a consistent severity-graded gate before main. A real 'claude code review skill' workflow.
The prompt
Use the requesting-code-review skill on the diff between origin/main and HEAD. Dispatch a general-purpose subagent as the reviewer — give it the diff and the original spec, NOT my session. Have it return strengths, then issues grouped Critical / Important / Minor, then an overall proceed-or-fix-first verdict with reasoning. I'll address Critical and Important before we merge.What slides.md looks like
Reviewer subagent (scoped to the diff + spec):
STRENGTHS
- Window math has boundary tests; headers match RFC draft.
ISSUES
[Critical] Redis client never closed on 429 path → leak under load.
[Important] default_limit hard-coded; spec says per-team configurable.
[Minor] nowSeconds() could be inlined.
VERDICT: Fix first. Address the 2 above, then re-review.One-line tweak
Add 'then run the receiving-code-review skill on its findings' so the agent triages each issue (fix vs justified push-back) instead of blindly applying everything.
Finish the branch cleanly (merge, tag, tear down)
Close out the feature properly — final verification, merge or PR, and remove the worktree — instead of leaving a half-cleaned branch and a stale checkout.
ForAnyone who finishes the code but leaves five abandoned worktrees and an un-pushed branch behind. The teardown half of the worktree workflow.
The prompt
The rate-limit feature passes verification. Use the finishing-a-development-branch skill: run the final test suite, push feat/api-rate-limit, open a PR with a body summarising the spec and the per-task commits, then remove the ../wt-api-rate-limit worktree so my checkouts stay clean. Don't delete the branch until the PR is open.What slides.md looks like
Final suite: ✓ 158 passed
Pushed feat/api-rate-limit → origin
Opened PR #482 'Per-team API rate limit'
- 5 tasks, 5 commits, links the design spec + plan
Removed worktree ../wt-api-rate-limit
(branch preserved; lives in the open PR)
Done. Your main checkout is clean.One-line tweak
Add 'squash the 5 task commits into one with a conventional-commit message' if your repo enforces a clean linear history.
Author your own composable skill (extend the framework)
Use the framework's own meta-skill to write a new, well-structured skill — correct frontmatter, a tight trigger description, and a flexible-vs-rigid classification.
ForPower users who want a house-style skill (your team's deploy ritual, your review checklist) that loads the same disciplined way as the built-ins.
The prompt
Use the writing-skills skill to author a new skill called 'release-checklist' for my team. It should trigger before any production deploy, enforce a fixed checklist (changelog updated, version bumped, migration plan attached), and be classified as a rigid skill. Write the SKILL.md with proper frontmatter and a description that's a precise trigger, not a summary. Save it under .claude/skills/release-checklist/.What slides.md looks like
---
name: release-checklist
description: Use before any production deploy — enforces changelog,
version bump, and an attached migration plan before release.
---
# Release checklist (RIGID — exact adherence)
Before deploy, you MUST confirm each, in order:
1. CHANGELOG.md has an entry for this version
2. version bumped in package.json + git tag prepared
3. migration plan attached or "no migrations" stated explicitly
→ Written to .claude/skills/release-checklist/SKILL.mdOne-line tweak
Add 'make it flexible, not rigid' if the checklist should adapt per project — the writing-skills skill changes the enforcement language accordingly.
Community signal
Three voices on Superpowers from people who use it for real work. The first is the maintainer’s own definition; the second is the most cited public endorsement; the third is a daily-use story where the brainstorming gate did exactly what use case 1 promises.
“Superpowers is a complete software development methodology for your coding agents, built on top of a set of composable skills and some initial instructions that make sure your agent uses them.”
Jesse Vincent (obra) · Blog
The repo README's canonical one-paragraph definition. Note the two halves: composable skills, plus instructions (the using-superpowers anchor) that force the agent to actually invoke them.
“I can't recommend this post strongly enough. The way Jesse is using these tools is wildly more ambitious than most other people.”
simonw (Simon Willison) · Hacker News
Top comment on the launch-day HN thread. Willison wrote his own companion walkthrough at simonwillison.net/2025/Oct/10/superpowers/.
“I watched Claude refuse to write code I asked it to write, because the design doc wasn't approved yet. A flat refusal, with the rationale spelled out in plain English, citing a hard gate inside something called the brainstorming skill.”
Tommaso Nervegna · Blog
A designer's adoption story. This is use case 1 in the wild — the brainstorming skill's gate blocking premature implementation. (Lightly trimmed to length; full text on the page.)
The contrarian take
Not everyone keeps the full loop. The most honest critique on the launch thread is from cruffle_duffle:
“Way to much babysitting and honestly writing docs and specs for them is more work than just writing parts of the code myself and letting the LLM do the tedious bits like finishing what I started. No matter what you are told, there is no silver bullet.”
cruffle_duffle · Hacker News
From the Superpowers launch HN thread.
Fair for small, well-understood fixes — the ceremony genuinely costs more than the code. But the objection inverts on large or long-running work: a precise spec and plan are exactly what let multiple agents run in parallel (use cases 4-5) and stay on-task across a long session without drifting. The right move isn't 'always' or 'never' — it's skip the loop for a one-file change, run it for engineering-grade output. That's the same line this cookbook draws.
One framing to keep straight: Superpowers is not Karpathy’s minimal CLAUDE.md philosophy, and it’s not Matt Pocock’s “skills are the npm moment” argument about distribution. Those are about how skills are written and shared. Superpowers is opinionated about process — it ships a specific methodology and forces the agent to follow it. Pick it when you want the discipline enforced, not when you want a light touch.
Real workflows shipped with Superpowers
Concrete examples of people running this workflow in public. None of these are marketing — they’re here so you have a target shape in mind before you write the prompt.
- Jesse Vincent (obra) — built and dogfoods Superpowers as his own daily coding-agent methodology, documenting the brainstorm/plan/TDD workflow
- Simon Willison — endorsed and demoed the workflow publicly and wrote his own walkthrough of what it enforces
- Tommaso Nervegna — designer using Superpowers for prototyping, hit the brainstorming skill's hard gate that refused to code before the design doc was approved
- Eric Tech — full video tutorial installing the plugin and running the TDD + planning loop on a real task
- GritAI Studio — video walkthrough taking a project through the brainstorm-to-implementation-to-test workflow
- Superpowers GitHub repo — the skills, install paths, and changelog Jesse maintains in the open (MIT)
Gotchas (the four that bite)
Sourced from the Superpowers launch thread and obra’s own release notes.
The full loop is token-hungry
Structured brainstorms, multi-page specs, and adversarial review loops all burn tokens before any code is written. On a rationed plan, running the whole loop on every task is a real cost. Reach for single sub-skills on small work.
Ceremony on small tasks
For a one-file bugfix the gate genuinely costs more than the fix. The contrarian objection above is correct in that regime — skip brainstorming and go straight to test-driven-development or just edit.
The anchor must be installed first
using-superpowers is what makes Claude actually invoke the other skills. Install the sub-skills without it and they sit dormant — Claude won't reach for them on its own.
It assumes you'll answer the questions
The brainstorming skill blocks on your input — one question at a time, waiting for approval. If you wanted a fully autonomous one-shot, this is the wrong tool; the gate is the feature, not a bug.
Pairs well with
Curated to match the cookbook’s actual integrations: the Superpowers sub-skills each recipe invokes, plus the MCP servers the debug, verify, and finish use cases (6, 7, 9) lean on.
Related skills
Related MCP servers
Two posts that compose well with this cookbook: What are Claude Code skills? covers the underlying mechanism, and Is Superpowers still worth it in 2026? is the adoption decision this how-to deliberately leaves alone.
Frequently asked questions
What is the using-superpowers skill and how is it different from the rest of Superpowers?
using-superpowers is the anchor skill of obra's Superpowers framework. It does not do brainstorming or planning itself — it's the instruction layer that makes Claude actually invoke the other skills (brainstorming, writing-plans, test-driven-development, requesting-code-review, and so on) instead of ignoring them. Install it first; it's what enforces the 'invoke a skill before responding' rule that the whole workflow depends on.
Do I have to use the whole brainstorm → plan → implement → review loop every time?
No, and you shouldn't. The full loop earns its tokens on ambiguous or large work where drift is the real risk. For a one-file bugfix it's ceremony. The skills trigger contextually, so you can also reach for just one — run test-driven-development on its own, or only requesting-code-review before a merge. Treat the cookbook above as ten independent recipes, not a mandatory pipeline.
Is this a good Claude Code skill for software architecture work?
Yes — the brainstorming and writing-plans sub-skills are the architecture-heavy part. brainstorming forces you to compare 2-3 approaches and write an approved design spec before any code; writing-plans decomposes that spec into a file-mapped, test-gated plan a fresh reviewer could execute. That front-loaded design discipline is the main reason teams adopt it for architecture-grade work rather than ad-hoc prompting.
How does the Superpowers code review skill work?
The requesting-code-review skill dispatches a general-purpose subagent as the reviewer and hands it only the git diff plus the original spec — not your chat history — so the review is scoped and unbiased. It returns strengths, then issues grouped Critical / Important / Minor, then a proceed-or-fix-first verdict. You address Critical and Important before merging, though you can push back with a technical justification via the receiving-code-review skill.
Does Superpowers really make the agent write tests first?
Yes — the test-driven-development sub-skill enforces strict red-green-refactor with one hard rule: 'no production code without a failing test first.' It makes the agent write the test, run it, and confirm it fails for the right reason before any implementation. If the agent writes code before the test, the skill's instruction is to delete it and start over. That 'watch it fail first' discipline is what Simon Willison highlighted in his write-up.
Is there a Superpowers MCP server, or is it skills-only?
Superpowers is a skills framework, not an MCP server — there is no 'Superpowers MCP'. The sub-skills do compose with MCP servers, though: use case 6 pairs systematic-debugging with the Sentry MCP for real stack traces, and use cases 7 and 9 pair verification and branch-finishing with the GitHub MCP. Skills decide the workflow; MCP servers give the agent the tools and data the workflow acts on.
Is it worth installing in 2026, or has Claude gotten disciplined enough on its own?
That's a separate question from how to use it — and we cover it in detail in our companion review, 'Superpowers for Claude Code: Still Worth It in 2026?'. Short version: newer models investigate and verify more on their own, which shrinks the harness's value on simple tasks, but the methodology still measurably helps on ambiguous and large work. This cookbook is the how-to; read the worth-it post for the adoption call.
Sources
Primary
- obra/superpowers (the framework repo + README)
- using-superpowers SKILL.md (the anchor skill)
- Jesse Vincent — the original Superpowers launch post
Community
- Jesse Vincent (obra) — Blog
- simonw (Simon Willison) — Hacker News
- Simon Willison — Blog
- Jesse Vincent (obra) — Blog
- Tommaso Nervegna — Blog
Critical and contrarian
Internal