Superpowers: The Spec-Driven Skill That Owns Your Whole Build

I have watched a lot of people give a coding agent a one-line prompt, hit enter, and then spend the next forty minutes fighting the result. The agent guessed. It built the wrong thing confidently and fast. The speed was real and the output was useless, and that combination is worse than slow because it feels like progress.

Superpowers is the skill that fixes the most expensive part of that loop: the rushing. The moment the agent realizes you are building something, it stops. It asks what you are actually trying to do. It works a spec out of the conversation, shows it to you, and only after you sign off does it write an implementation plan — and then it hands that plan to subagents that build and review each other's work. It is, at the time of writing, the most-starred agent skill on GitHub, sitting at roughly 226k stars, ahead of Vue and Next.js. That number alone should make you curious. The methodology behind it is what should make you adopt it.

This article is the full tour. I will explain what an agent skill is, what Superpowers actually does, why the spec-first approach works, how to install and drive it across Claude Code and other agents, how the build/review subagent loop functions, the token-cost tradeoff you are signing up for, and the pitfalls that will bite you if you are not paying attention.

What an "agent skill" actually is

Before Superpowers makes sense, the format it ships in has to make sense.

An agent skill is a directory with a SKILL.md file inside it. That file has three things that matter:

1. A name.
2. A one-line description that tells the agent when this skill is relevant.
3. A body of instructions — plain Markdown — that the agent reads and follows when the skill triggers.

That is the whole format. It started at Anthropic as a way to package reusable agent behavior, and it has since spread well past Claude Code. The same SKILL.md convention runs in Cursor, Kiro, Codex, Gemini CLI, and a growing list of other agents. The portability is the point: you write the behavior once, in Markdown, and it travels.

The mental model I give people is this:

A skill is not a plugin and it is not an API. It is a set of instructions your agent reads at the right moment and chooses to follow. The "right moment" is decided by the one-line description, which the agent matches against what you are doing.

That description line is doing a surprising amount of work. It is the trigger. A good skill description reads like "use this when the user is starting to build a feature, write code, or implement something non-trivial." A bad one is vague and either never fires or fires constantly. Superpowers lives or dies on getting that trigger right, and it gets it right.

Why Markdown instructions beat hard-coded tools

People are sometimes disappointed that a skill is "just Markdown." That reaction misunderstands where the leverage is. The model is already capable. What it lacks in the moment is discipline — a reliable sequence of steps it will follow under pressure instead of doing the fast, wrong thing. Markdown instructions are exactly the right medium for encoding discipline, because they can be specific, conditional, and human-auditable. You can read a skill and know precisely what it will make your agent do. Try that with a compiled tool.

What Superpowers does, end to end

Superpowers is not a small helper. It is an opinionated, complete development methodology that takes over the moment you start building. Here is the flow it imposes, in order.

1. It catches you starting to build

You do not invoke Superpowers with a slash command every time. You install it once, and then it watches. The skill's trigger fires when the agent detects that you are doing implementation work — "add a feature," "build an endpoint," "refactor this module," "make a small script that…". The instant it fires, the agent stops generating code and changes posture.

This single behavior is the most valuable thing in the package. Most bad agent output comes from the agent answering a question you did not fully ask. Superpowers refuses to answer until the question is clear.

2. It interviews you

Instead of guessing, the agent asks. Not a wall of forty questions — a focused interview aimed at the ambiguity that actually matters for this task. What is the goal behind the goal? Who uses this? What are the constraints? What does "done" look like? What is explicitly out of scope?

The interview is short by design, but it is real. It is the difference between an agent that builds what you said and an agent that builds what you meant.

3. It works a spec out of the conversation

From the interview, Superpowers produces a specification — a written document describing what is being built and why, the requirements, the constraints, and the acceptance criteria. Crucially, this spec is derived from the back-and-forth, not invented in a vacuum. It reflects the decisions you actually made.

You can have the agent show you the spec inline, and on supported setups it can render it in a browser for review. This is the checkpoint. Nothing gets built until you read this and agree.

4. You sign off

This is a hard gate, not a soft suggestion. The agent will not move to implementation until you approve the spec. If the spec is wrong, this is where you catch it — when fixing it costs one sentence instead of one afternoon of generated code.

5. It writes an implementation plan

Once you approve the spec, Superpowers writes a separate implementation plan: the concrete steps, the files, the order of operations, the testing strategy. The spec is the "what and why." The plan is the "how." Keeping them separate is deliberate, because it lets you approve intent before you approve mechanics.

6. It hands the plan to subagents

Here is where it gets genuinely clever. Superpowers does not just run the plan in one long context. It dispatches work to subagents — separate agent instances with their own context — that build pieces of the plan and then review each other's work. One subagent implements; another inspects the implementation against the spec and the plan and pushes back on what is wrong.

That build/review loop is the part that makes the output trustworthy, and it deserves its own section.

Why spec-first works (the real reason)

It is tempting to think the value here is "documentation." It is not. The value is error cost timing.

Every project has a fixed amount of ambiguity that has to get resolved. You can resolve it cheaply, at the start, in plain language — or you can resolve it expensively, at the end, by reading and rewriting generated code. The total ambiguity does not change. Only when and how much it costs to fix changes.

A rushing agent pushes all of that resolution to the end. You discover the misunderstanding by reading three hundred lines of code that implemented the wrong assumption. Superpowers pulls the resolution to the front, where each fix is a sentence.

Here is the same idea as a table, because it is the single most important argument for the whole approach:

Decision point	Cost to change if caught here	What you are editing
During the interview	Trivial	A spoken answer
In the spec, before sign-off	Very low	A line of prose
In the implementation plan	Low	A planned step
In generated code, mid-build	Medium	Real code + its dependents
After "done," in review	High	Code, tests, and your trust in the agent

Every row down that table is more expensive than the one above it. Spec-first development is, mechanically, just "resolve ambiguity as high in that table as possible." Superpowers enforces it so you do not have to remember to.

There is a second, quieter reason it works: the spec is a contract the reviewer subagent can check against. Without a written spec, "is this correct?" has no answer — correct relative to what? With a spec, review becomes a concrete comparison: does the implementation satisfy these criteria, yes or no? That is what turns the review step from vibes into verification.

The subagent build/review loop

Let me unpack the part that makes Superpowers more than a fancy planning prompt.

When the implementation plan is approved, Superpowers does not pour all the work into one ever-growing conversation. It spins up subagents. A subagent is a fresh agent instance with its own context window and a narrow assignment. This matters for two reasons:

• Clean context. A subagent assigned to "implement the auth middleware per step 3 of the plan" is not carrying the noise of the entire conversation. It sees the spec, the plan, the relevant files, and its task. Focused context produces focused work.
• Independent review. The reviewing subagent did not write the code, so it is not anchored to the author's assumptions. It reads the implementation against the spec and the plan and reports what does not match. This is adversarial in the healthy sense — the reviewer's job is to find problems, not to bless the work.

The loop looks like this:

1. A builder subagent implements a slice of the plan.
2. A reviewer subagent checks that slice against the spec, the plan, and the acceptance criteria.
3. Findings come back. If the reviewer flags real issues, the work goes back for revision.
4. Repeat per slice until the plan is satisfied.

spec.md  ──►  plan.md  ──►  [builder subagent]  ──►  diff
                                  │                     │
                                  ▼                     ▼
                          [reviewer subagent]  ◄──  checks vs spec/plan
                                  │
                          findings ──► revise or accept

You, the human, sit above this loop. You approved the spec and the plan, and you see the review findings. You are not babysitting individual lines; you are supervising a process that has its own internal quality control. That is the actual "superpower" — not that the agent codes, but that it self-corrects against a contract you signed off on.

Why separate contexts beat one big context

A single long context degrades. The more you cram into one conversation — the interview, the spec, the plan, every file, every revision — the more the model has to weigh against the task in front of it, and the more likely it is to lose the thread. Subagents sidestep this by giving each unit of work a clean, scoped context. It is the same instinct as keeping functions small: bounded scope, bounded surface for mistakes.

Installing and driving it

Superpowers is distributed through the official Claude plugin marketplace, and it is also available for Codex, Cursor, Gemini CLI, and others. If you use Kiro, you can pull it in via Skills.sh. The portability of the underlying skill format is exactly why it can live in so many places.

Claude Code

The fastest path is the plugin install from the official marketplace:

/plugin install superpowers@claude-plugins-official

That registers the skill and its trigger. From there you do not need to call it explicitly — start describing something you want to build, and Superpowers will catch the intent and begin the interview.

If you prefer to wire it up from the repository directly, clone it and follow the install instructions in the README:

git clone https://github.com/obra/superpowers.git
# then follow the repo's install instructions for your agent

Other agents

• Cursor / Codex / Gemini CLI: install via their respective skill/plugin mechanisms; the same SKILL.md content drives the behavior.
• Kiro: add it through Skills.sh, which exposes the skill to Kiro's runtime.

The thing to internalize is that you are installing behavior, not a binary. Once it is in place, the way you "drive" it is by talking normally and letting the trigger do its job.

How to actually steer it once it fires

A few habits make the experience far better:

1. Answer the interview honestly and briefly. It is asking because the answer changes the build. Vague answers produce a vague spec.
2. Read the spec like it is a contract, because it is. This is your cheap checkpoint. Spend two real minutes here. It will save you thirty later.
3. Reject the spec when it is wrong. Do not approve to "move things along." An approved-but-wrong spec poisons everything downstream, including the reviewer, which now checks against the wrong target.
4. Let the review loop run. Resist the urge to grab the wheel after the first builder pass. The reviewer often catches things you would have missed.

When to use Superpowers — and when not to

This is the part most write-ups skip, and it is the part that determines whether you are happy with the tool. Superpowers is heavy. That weight is an asset for some tasks and pure overhead for others.

Use it when

• The task is non-trivial — a real feature, a module, a service, anything with more than one moving part.
• The requirements are ambiguous and the cost of building the wrong thing is high.
• You want auditable output — a spec and a plan you can point to and that a reviewer can check against.
• Multiple things have to fit together correctly, where a single wrong assumption cascades.

Reach for something lighter when

• You are doing a one-line fix or a tiny script where the interview costs more than the mistake would.
• You are exploring — throwaway spikes, quick experiments — where a rigid spec gate just slows you down.
• You are token-constrained and the task does not justify the spend (more on this next).

For those lighter cases, I lean on more focused skills. If you want disciplined-but-leaner spec habits, look at gsd-core. If you want a clean Git-and-stack workflow without the full methodology, gstack is the right altitude. And if you want to interrogate your own plan before committing to it, grill-me is a sharp little tool for exactly that.

Here is a rough decision guide:

Situation	Tool	Why
Real feature, fuzzy requirements	Superpowers	Spec gate + review loop pays for itself
Small, clear change	Lighter skill or plain prompt	Interview overhead not worth it
Throwaway experiment	Plain prompt	Don't gate exploration
Need an auditable trail	Superpowers	Spec + plan are the artifacts
Tight token budget, medium task	gsd-core / gstack	Most of the discipline, less spend

The token-cost tradeoff

I am not going to pretend this is free, because it is not. Superpowers can burn a lot of tokens. You are paying for:

• The interview — multiple turns of back-and-forth.
• The spec — a written document, generated and possibly revised.
• The plan — a second written document.
• The subagents — each one has its own context, and the reviewer reads the implementation in addition to the builder writing it. Build and review means the work gets processed more than once.

That is a meaningfully larger spend than firing a single prompt at a single context. The honest framing is a trade:

You are spending more tokens up front to spend far fewer of your own tokens — the human ones — on cleanup, rework, and re-explaining what you actually wanted.

For a task where building the wrong thing costs you an afternoon, that trade is obviously worth it. For a five-minute fix, it is obviously not. The skill of using Superpowers well is mostly the skill of knowing which kind of task you have in front of you.

A few ways to keep the cost sane:

1. Don't use it for trivial work. This is the biggest lever by far.
2. Keep the spec tight. A focused spec means a focused plan means focused subagents. Sprawl is what runs up the bill.
3. Scope the plan into clean slices. Well-bounded subagent tasks process less redundant context than vague ones.
4. Catch errors at the spec gate. Every error you fix in prose is an error you did not pay to fix in code and then re-review.

Pitfalls and how to avoid them

I have seen these go wrong in predictable ways. Here is the list, with the fix for each.

Approving a spec you didn't read

The spec gate only works if you actually use it. Rubber-stamping the spec to get to the code defeats the entire methodology and, worse, aims the reviewer subagent at the wrong target. Fix: treat spec approval as the most important two minutes of the build.

Using it for everything

If you let Superpowers interview you about a one-line CSS tweak, you will resent it, and you should. Fix: reserve it for non-trivial work and keep lighter tools in reach for the rest.

Fighting the interview

People sometimes try to bypass the questions and shove the agent straight to code. You can, but you are throwing away the thing you installed it for. Fix: answer the questions; they are short and they are load-bearing.

Ignoring the review findings

The reviewer subagent exists to disagree with the builder. If you skim past its findings to ship faster, you have turned off the quality control. Fix: read the findings; they are the cheapest bug reports you will ever get.

Letting the spec drift from reality

If requirements change mid-build and you do not update the spec, the reviewer is now checking against a stale contract. Fix: when the goal changes, change the spec first, then continue.

Token sticker shock

If you run it on everything without thinking, the bill will surprise you. Fix: match the tool to the task. The cost is justified by the stakes; on low-stakes work there is nothing to justify it.

A short worked example

Say you ask for "an endpoint to export user data as CSV." A rushing agent picks a format, a column set, an auth model, and an error behavior — all guessed — and writes it. Superpowers instead asks:

• Which users can export? Just themselves, or admins exporting others?
• Which fields, and in what order?
• What about users with thousands of rows — stream or paginate?
• What should happen on a partial failure?
• Is there a PII or compliance constraint on what can be exported?

Those five questions are the entire difference between a CSV endpoint you ship and a CSV endpoint you rewrite. They take two minutes. From your answers it writes a spec — "authenticated users export their own records; columns X, Y, Z; streamed for large sets; 4xx with a typed error on partial failure; email column redacted per policy." You read it, you fix the one thing it got wrong, you approve. Then the plan, then a builder subagent, then a reviewer subagent confirming the implementation matches every line of that spec.

That is the whole pitch in one example: the questions are cheap, the spec is a contract, the review is verification, and the wrong build never gets written.

If you want to go deeper on the philosophy underneath this, I wrote a full guide on spec-driven development with AI agents, and Superpowers is the headliner in my roundup of the most popular AI coding skills. If you are assembling a whole workflow rather than evaluating one tool, the agentic automation track walks through how these pieces fit together.

The bottom line

Superpowers is the most-starred agent skill on GitHub for a reason that has nothing to do with hype. It encodes a single, correct idea — resolve ambiguity before you write code, and verify code against a contract you signed off on — and it enforces that idea with a spec gate and a subagent review loop instead of trusting you to remember. It costs more tokens. It is overkill for trivial work. And for any real build with fuzzy requirements, it is the difference between an agent that is fast-and-wrong and one that is deliberate-and-right.

Install it, use it on something that matters, and pay real attention at the spec gate. That is where the whole thing earns its name.

Resources & links

• Superpowers on GitHub (obra/superpowers) — the source repository, install instructions, and the methodology itself.
• Claude Code plugin marketplace — where the /plugin install superpowers@claude-plugins-official command pulls from.
• Cursor — one of the agents the skill format runs in.
• Kiro — usable via Skills.sh.
• Skills.sh — distribution path for bringing skills into agents like Kiro.
• Superpowers skill page (this site) — the at-a-glance reference for this skill.
• GSD Core skill — leaner spec-driven discipline when Superpowers is too heavy.
• gstack skill — a clean Git-and-stack workflow for lighter tasks.
• grill-me skill — interrogate your own plan before you commit to it.
• Spec-driven development with AI agents (guide) — the philosophy behind the spec gate.
• The most popular AI coding skills (guide) — where Superpowers ranks and why.
• Agentic automation track — how these skills combine into a full workflow.