Inside obra/superpowers: How a Skill Pack Gets Coding Agents to Follow a Process

Superpowers is a set of agent skills that makes Claude Code, Codex, Cursor and a dozen other agents brainstorm, plan, test first and review before they call work done. How it loads itself into every session, what each step does, what the release notes measured, and what it costs you.

Rahul Bisht

Founder, CrawlPilot

·
Nov 13, 2026
·
Verified Nov 13, 2026
·AI & Agents·
14 min read
·
Inside obra/superpowers: How a Skill Pack Gets Coding Agents to Follow a Process
Key takeaway
Superpowers is fifteen Markdown skills plus a small startup hook, and the hook does most of the work. It loads one skill into every session that tells the agent to check for a relevant skill before it does anything, then lists the excuses agents give for skipping one. The rest is a fixed path from question to merged branch: brainstorm, plan, test first, review, verify. It costs more tokens and more patience than letting an agent just code. Its maintainers test each change against recorded sessions and publish the results, which few skill packs do.

The first thing Superpowers puts into your coding agent's context is a rule written in capitals: "If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill." That line, from the using-superpowers skill, explains most of how the project works. Agents are good at writing code and bad at stopping first to ask what you want, write a plan, or watch a test fail. Superpowers handles that with skills the agent finds hard to talk itself out of loading.

It has become one of the most-starred projects on GitHub; AgentConn put it at 252,000 stars during the run of agent-skill repos up the trending page this year. Version 7.0.2 shipped on November 3, 2026, and everything below comes from reading the repository at that release.

What you install

Superpowers is a folder of Agent Skills: each skill is a directory with a SKILL.md file that an agent loads when the skill's description matches the task. The README lists install steps for sixteen agents. In Claude Code it is one command from Anthropic's official marketplace:

bash
/plugin install superpowers@claude-plugins-official

The repository holds fifteen skills in four groups: testing (test-driven-development), debugging (systematic-debugging, verification-before-completion, diagnosing-superpowers), collaboration (brainstorming, planning, executing plans, code review, git worktrees, parallel agents, subagent-driven development) and meta (writing-skills, using-superpowers). It is MIT licensed and built by Jesse Vincent and the team at Prime Radiant, who also sell enterprise support.

How it gets into every session

A skill only helps if the agent loads it, and agents often decide a task is too small for one. Superpowers deals with that before you type anything. Step through it:

How the Superpowers bootstrap reaches the model
1reads SKILL.md231% rule3Session startsor /clear, or compactionSessionStart hookhooks/session-startusing-superpowersinjected into contextYour request"add a settings page"brainstormingloaded before any code
  1. A session starts. On Claude Code and most other agents, the plugin registers a SessionStart hook, which also runs after /clear and after the context is compacted.
  2. The hook reads the using-superpowers skill from disk and injects it into the conversation, before you have typed anything.
  3. You ask for something. The injected rule says to invoke any skill with even a 1% chance of applying before replying, so a build request loads brainstorming before any code is written.

3 steps. Press Play to walk through them, or click any part of the diagram.

A session-start hook injects the using-superpowers skill, which makes the agent check its skills before replying

The hook is written with more care than it looks. Version 7.0.0 stopped it from looking up dirname, cat or bash on PATH, because a broken startup PATH in Claude Code had been silently dropping the bootstrap. Version 7.0.2 made it start no child processes at all, since each one costs tens of milliseconds under Git Bash on Windows. Both changes are in the release notes. Agents without a startup hook, such as Antigravity, get the same effect a different way: the skill's description says "Use when starting any conversation", and the team reports that across 12 test runs this was enough to trigger brainstorming before any code.

The injected skill also has a table of the thoughts an agent has just before it skips a skill, each paired with a reply: "This is just a simple question" against "Questions are tasks. Check for skills.", and "Let me explore the codebase first" against "Skills tell you HOW to explore." Turn each safeguard off below to see what it prevents:

The agent checks its skills and follows the process. Every safeguard below is in place.

  1. Startup bootstraphandled

    What happens without it: The agent never learns the skills exist, so it starts coding straight from your first message. Where it lives: SessionStart hook injecting using-superpowers.

  2. The 1% rulehandled

    What happens without it: The agent loads skills only when a task looks big, and most tasks look small at first. Where it lives: using-superpowers, in capitals.

  3. Red-flags tablehandled

    What happens without it: The agent talks itself out of a skill: just a quick question, let me look around first. Where it lives: a table of excuses with a reply to each.

  4. Iron lawshandled

    What happens without it: The agent writes code and adds tests afterwards that pass on the first run, so they never prove anything. Where it lives: test-driven-development: code written before its test is deleted.

  5. Fresh reviewershandled

    What happens without it: The agent grades its own work and calls it done. Where it lives: a new subagent reviews each task, then the whole branch.

What keeps a Superpowers agent on the process, as the repository's skills describe it. Turn one off to see what slips.

The path from request to merged branch

Once a request comes in, the README lays out seven skills that fire in order. Each one activates on its own when its moment comes:

The Superpowers workflow
122test first34Brainstormwhat and whyWorktreeclean branchPlan2 to 5 min tasksExecutesubagent per taskReviewspec, then qualityFinishmerge, PR or discard
  1. Brainstorming finds out what you want and why, plays it back for you to correct, and sizes the work: a quick fix gets done, a small change is agreed in chat, a project gets a design document.
  2. After you approve the design, it opens an isolated git worktree on a new branch, checks the tests pass, and writes a plan of tasks that each take 2 to 5 minutes, with exact file paths and verification steps.
  3. Execution follows test-driven development: write a failing test, watch it fail, write the least code that passes, commit.
  4. Each task is reviewed against the plan. When all tasks are done, the agent verifies the tests and offers to merge, open a PR, keep the branch or discard it.

4 steps. Press Play to walk through them, or click any part of the diagram.

Seven skills in order, from finding out what you want to merging the branch

The plan step has a memorable bar. The README says the plan must be clear enough for "an enthusiastic junior engineer with poor taste, no judgement, no project context, and an aversion to testing" to follow. That is a fair description of a fresh subagent, which is who will read it.

The test-first rule is strict. The test-driven-development skill says to delete code written before its test, even code you meant to keep as a reference. That will annoy you the first time it happens. It is also how you know the test can fail at all: a test written after the code tends to pass on its first run, so nobody ever sees it catch anything.

Two ways to run the plan

There are two execution skills, and the choice is a straight trade between tokens and thoroughness:

subagent-driven-development
  • Problems are caught one task at a time
  • Pays for a fresh context per task and per review
  • A fresh subagent implements each task, with only the context it needs
  • A task review after each one: spec compliance, then code quality
  • A broad review of the whole branch at the end
executing-plans
  • The cheapest way to run a plan
  • Mistakes surface only in the final review
  • Every task runs inline in the current session
  • One fresh review of the whole branch at the end

Verdict: Use subagents when tasks are independent and worth checking one by one; run inline when the tasks are tightly linked or tokens are tight.

The two ways Superpowers runs a plan, from the subagent-driven-development and executing-plans skills

Subagent-driven development also tells the controlling agent not to stop and check in between tasks. It may stop for four things only: an irreversible or destructive operation, a security-sensitive action, a side effect outside the worktree such as a merge or a push, or a plan so broken that every path forward is a guess. Anything else it decides itself, writing each decision into a ledger with what it would cost if wrong. The README says it is common for an agent to work through a plan for a couple of hours on its own this way.

What the release notes measured

The maintainers test skill changes against recorded scenarios, and they publish the numbers. The brainstorming rewrite in 7.0.2 is the clearest example. In blind-graded test conversations, the number of filler questions, those that would not change what got built, moved like this across three versions:

Filler questions asked by the brainstorming skill across the same blind-graded test scenarios (lower is better)

The same notes report that 7.0.2 got the reason behind a request before proposing any approach in 33 of 33 conversations, against 19 of 33 for 6.4.2, and built nothing before approval in any of them. In one scenario, a spec assigned Ctrl+K to two features. Version 7.0.1 found the conflict every time but asked a bare "which one?" in 8 of 8 runs; 7.0.2 laid out the options with a recommendation in 8 of 8.

These come from the maintainers' own test harness, so treat them as their measurements rather than an independent benchmark.

What it costs

Superpowers trades speed and tokens for fewer wrong turns. A few things to know before installing it everywhere:

  • It slows small tasks down. Brainstorming tries to size the work and just do quick, clear requests, but the skill check still runs on every message, and the test-first rule still applies to every bug fix.
  • Subagent review costs tokens. A fresh context per task and per review adds up on a long plan. Use executing-plans when the budget matters.
  • The visual companion phones home by default. Brainstorming's optional visual companion loads the Prime Radiant logo from their site, with the plugin version in the request. The README says nothing about your project is sent, and setting SUPERPOWERS_DISABLE_TELEMETRY turns it off, as do Claude Code's own telemetry opt-outs.
  • The project won't take your skills. The contributing guide says the project generally doesn't accept new skills and won't take agent-written PRs for issues someone else filed. Put your own skills in your own plugin.

When a session goes wrong, the diagnosing-superpowers skill reads the transcript and reports which skill fired, which didn't, and where the agent left its plan, with line-level evidence.

What to take from it for your own skills

Even if you never install it, Superpowers is the best worked example I have found of how to write skills that agents follow. Its writing-skills skill treats a skill like code under test. You first run a pressure scenario without the skill and watch the agent break the rule (time pressure, sunk cost, a tired user). Then you write the skill and run the scenario again. Then you close the loopholes the agent found. It also warns that the right form depends on how the agent failed: an agent that skips a rule it knows needs a prohibition and a table of excuses, and soft wording such as "prefer" or "consider" makes that worse.

That matches what I see writing skills for this site's own blog pipeline. A rule the agent can see the reason for gets followed; a rule stated once in passing gets skipped the first time the agent is in a hurry.

Check yourself

Q1On Claude Code, how does the using-superpowers skill reach the model before you type anything?

Q2Under the test-driven-development skill, what happens to code written before its test?

Cheat sheet
obra/superpowers at a glance

Install

  • Claude Code: /plugin install superpowers@claude-plugins-official
  • Sixteen agents supported; install separately for each.
  • MIT licensed; v7.0.2 shipped November 3, 2026.

How it loads

  • A SessionStart hook injects using-superpowers.
  • The 1% rule: check for a skill before any reply.
  • A table of excuses agents use to skip skills.

The workflow

  • Brainstorm, worktree, plan, execute, review, finish.
  • Tasks of 2 to 5 minutes with exact file paths.
  • Test first; code written before its test is deleted.

Costs

  • More tokens: a fresh context per task with subagents.
  • Slower on small fixes.
  • Visual companion telemetry: SUPERPOWERS_DISABLE_TELEMETRY.

Sources