Skip to main content

Superpowers by obra: what it contains and how to install it

Superpowers is a method made of skills for Claude Code: how to install it, which skills it really contains, and how to check the descriptions you write.

What do you think about this article?

Superpowers by obra: what it contains and how to install it
Sub-pagePhoto:PixabayPexels

At a Glance

Superpowers is a method made of skills for Claude Code: how to install it, which skills it really contains, and how to check the descriptions you write.

If every time you ask an assistant to fix a bug you have to remind it to look for the cause first, or to write the test before the code, you are paying by hand for something a skill can enforce on its own. Superpowers, the project by obra, is a set of skills of this kind for Claude Code: not a catalogue to browse, but a way of working that the assistant applies when the situation calls for it. Here I tell you what it really contains, how to install it, and where I have seen the skills work or not work.

Independence: I am not affiliated with obra or with Anthropic, and there are no affiliate links. The statements about the project come from its repository and from the Claude Code documentation, read on 2026-11-13; when I tell an experience of my own I declare it as a story, without percentages. For the overall picture of the series start from the opening guide; Get Shit Done is left out here, and has its own page.

What Superpowers is, without the word marketplace

The README describes it as a complete software development methodology for coding assistants, built on composable skills and on initial instructions that make the assistant use them. The repository is published under the MIT licence. The marketplace, which is often used as a synonym, is something else: it is only the channel the plugin is installed from, and the plugin contains the skills. The difference matters because it changes the expectation: you do not pick skills one by one from a shelf, you install a method in which the skills call one another.

The skills of version 5.1.0, the one installed on the machine where I prepared the article, are fourteen, and the README adds a fifteenth, diagnosing-superpowers, which is not in 5.1.0. They fall into three families: collaboration (design, plan, execute, review, close a branch), proof and debugging (TDD, systematic debugging, verification before declaring done) and skills about skills (writing-skills, using-superpowers). There is no skill called code-reviewer, tdd-guide or refactor-cleaner: those names, if you have seen them around, belong to skills and agents written by others or by me.

How to install it

In Claude Code the plugin is installed from Anthropic's official marketplace or from the author's own. The commands are those of the README, Claude Code section:

/plugin install superpowers@claude-plugins-official

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

They are two alternatives: the first line is enough; the last two first register the author's marketplace and then install from there. They are commands internal to Claude Code and I did not run them (schema to adapt). You will find it written elsewhere to clone the repository into ~/.claude/skills/: that is not the procedure the README documents for Claude Code. The documented route is the plugin, and its skills are invoked with the plugin name as a prefix, because the Claude Code documentation says that plugin skills have their own namespace.

The same README lists installation for other environments, including Codex, Cursor, Gemini CLI and GitHub Copilot CLI: Superpowers does not depend on Claude Code, even though here we only talk about that case. How the plugin is updated or pinned to a version I did not verify: if you need it, look for the procedure in the Claude Code plugin documentation.

When a skill starts, and what it does

Every skill has a frontmatter with a name and a description. Claude Code always keeps the description in the context and loads the body only when it decides it is needed, as article 02 explains. Here are the real descriptions of seven skills of the plugin, copied from the files, and what each one enforces according to the body of the file.

SkillDescription (from the file)What it enforces
brainstormingYou MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation.Understand the intent before building
writing-plansUse when you have a spec or requirements for a multi-step task, before touching codeA plan made of small tasks before the code
test-driven-developmentUse when implementing any feature or bugfix, before writing implementation codeNo production code without a failing test first
systematic-debuggingUse when encountering any bug, test failure, or unexpected behavior, before proposing fixesNo fix without having investigated the cause
requesting-code-reviewUse when completing tasks, implementing major features, or before merging to verify work meets requirementsReview against the plan, with severity
verification-before-completionUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions alwaysProof before saying «done»
subagent-driven-developmentUse when executing implementation plans with independent tasks in the current sessionOne sub-agent per task, with two-stage review

Read the middle column: almost every description says when to use the skill («Use when...») and not what it does, and that is no accident. The writing-skills skill explains why: in the author's tests, when the description summarised the procedure, Claude tended to follow the summary instead of reading the body of the skill, and the body became documentation that got skipped. A description that only says when to use it forces the reading of the rest. Be careful, because the Agent Skills specification, which is another source, asks for a description that says both what the skill does and when to use it: this is a design choice of Superpowers, motivated by its tests, and not a requirement of the format. The two most evident exceptions, brainstorming and verification-before-completion, show that the author himself does not follow the rule rigidly.

A checkable rule: the script that reads the descriptions

The formal rules of writing-skills can be checked with a few lines: the description starts with «Use when», does not exceed 500 characters (the limit the skill recommends «if possible»), and is a single sentence. The script below applies those three checks to three samples of mine and to the plugin's skills; it does not understand the meaning of the sentences, so it does not replace judgement, but it immediately finds the descriptions that look like summaries.

"""Checks the form of skill descriptions (formal rules only, not the meaning)."""
import glob
import os
import re
import sys


def descrizione(percorso):
    testo = open(percorso, encoding="utf-8").read()
    frontmatter = re.match(r"---\n(.*?)\n---\n", testo, re.S).group(1)
    return re.search(r"^description:\s*(.+)$", frontmatter, re.M).group(1).strip()


def problemi(testo):
    trovati = []
    if not testo.lower().startswith("use when"):
        trovati.append("does not start with 'Use when'")
    if len(testo) > 500:
        trovati.append(f"{len(testo)} characters (over 500)")
    if re.search(r"[.;] \S", testo):
        trovati.append("more than one sentence: it risks summarising the procedure")
    return trovati


campioni = {
    "sample-ok": "Use when a test fails only on CI and not on the developer machine",
    "sample-summary": "Use when investigating a bug. Drives a scientific-method loop (hypothesis, test, measure) and creates checkpoints between cycles.",
    "sample-vague": "Helps with debugging",
}
for nome, d in campioni.items():
    print(f"{nome}: {problemi(d) or 'ok'}")

print("--- plugin skills")
for percorso in sorted(glob.glob(os.path.expanduser(sys.argv[1]))):
    nome = percorso.split("/")[-2]
    print(f"{nome}: {problemi(descrizione(percorso)) or 'ok'}")

# Output (python3 -I lint_descrizioni.py with the path of the skills of plugin 5.1.0):
# sample-ok: ok
# sample-summary: ['more than one sentence: it risks summarising the procedure']
# sample-vague: ["does not start with 'Use when'"]
# --- plugin skills
# brainstorming: ["does not start with 'Use when'", 'more than one sentence: it risks summarising the procedure']
# dispatching-parallel-agents: ok
# executing-plans: ok
# finishing-a-development-branch: ok
# receiving-code-review: ok
# requesting-code-review: ok
# subagent-driven-development: ok
# systematic-debugging: ok
# test-driven-development: ok
# using-git-worktrees: ok
# using-superpowers: ok
# verification-before-completion: ['more than one sentence: it risks summarising the procedure']
# writing-plans: ok
# writing-skills: ok

The output confirms what the table suggested: twelve skills out of fourteen pass, and the two that do not are brainstorming (it starts with «You MUST») and verification-before-completion (it contains a semicolon and its procedure). The «summary» sample has the procedure (hypothesis, test, measure) written in the description: the rule flags it for exactly that reason. Run twice, identical output; the results hold for version 5.1.0.

What «test before code» means: an example you can redo

The test-driven-development skill states its law in one line: no production code without a failing test first; if you wrote the code before the test, you delete it and start over. It is a hard rule, and the best way to understand it is to see it on a small case. The domain is a quantity discount calculation: ten per cent from ten pieces, twenty per cent from fifty, an error below one piece. First I write the tests, in a test_discount.py file:

import unittest

from discount import discounted_price


class TestDiscount(unittest.TestCase):
    def test_no_discount_below_ten_pieces(self):
        self.assertEqual(discounted_price(9, 20.0), 180.0)

    def test_ten_percent_above_ten_pieces(self):
        self.assertEqual(discounted_price(25, 20.0), 450.0)

    def test_twenty_percent_from_fifty_pieces(self):
        self.assertEqual(discounted_price(50, 20.0), 800.0)

    def test_invalid_quantity(self):
        with self.assertRaises(ValueError):
            discounted_price(0, 20.0)


if __name__ == "__main__":
    unittest.main()

Each test states a rule with a number you can check in your head: nine pieces at twenty euros make 180 with no discount, twenty-five make 450 with the ten per cent, fifty make 800 with the twenty, and zero pieces is an error. You run it before discount.py exists, and it must fail: that is the red. Then you write the minimal implementation and run it again.

# discount.py
def discounted_price(quantity, unit_price):
    """Total for `quantity` pieces: -10% from 10 pieces, -20% from 50 pieces."""
    if quantity < 1:
        raise ValueError("quantity must be at least 1")
    if quantity >= 50:
        factor = 0.80
    elif quantity >= 10:
        factor = 0.90
    else:
        factor = 1.0
    return round(quantity * unit_price * factor, 2)

# Output of tdd_run.sh (red without discount.py, then green with discount.py):
# == ROSSO
# ERROR: test_discount (unittest.loader._FailedTest.test_discount)
# ModuleNotFoundError: No module named 'discount'
# Ran 1 test
# FAILED (errors=1)
# == VERDE
# test_invalid_quantity ... ok
# test_no_discount_below_ten_pieces ... ok
# test_ten_percent_above_ten_pieces ... ok
# test_twenty_percent_from_fifty_pieces ... ok
# Ran 4 tests
# OK

The red here is an import error, because the module does not exist yet: it is the crudest form of a failing test, but it serves to show that the test does not pass «by chance». In the green, the thresholds sit in the two conditions quantity >= 50 and quantity >= 10, evaluated from the highest to the lowest; if you swapped them, fifty pieces would get the ten per cent and the third test would turn red, which is exactly the error the initial red lets you discover. Run twice with identical output; the timings were removed because they vary. This is a demonstration of mine on a test project: it proves nothing about what Claude does with the skill, for that you need real sessions. On my real project I happened to use the same discipline for a service that calculates a career level, and that is where I started to trust it.

Mistakes made when writing skills

The three indications that follow come from experience and from the documentation, and I keep them separate because they carry different weights.

  • A skill that summarises itself in its description. It is the mistake documented by writing-skills: the description says when, the body says how.
  • A skill that duplicates a built-in feature. The Claude Code documentation reminds you that built-in features, such as the /debug or /code-review commands, already exist: check before writing an identical one.
  • A skill that claims to do everything. The body grows, the description widens and the match against the request becomes vague; splitting it into precise tasks is the remedy I apply.

On size I do not repeat my old three-hundred-line rule, because the measurement refutes it: in the plugin, test-driven-development has 367 lines of body and writing-skills has 651. The Agent Skills specification recommends a body under 500 lines and under 5,000 tokens, and it is a more honest criterion. The limit is not a number, it is the question: does the model still understand when to invoke it?

When not to use it

Superpowers is not a universal insurance policy. For a one-line request, such as changing a colour, activating a method costs more than it is worth; for a prototype you will throw away it makes no sense to impose the test before the code, and it is the README itself, in the list of exceptions of test-driven-development, that mentions throwaway prototypes, generated code and configuration files. It also holds for your own skills: write a skill when you have done the same thing by hand several times, not the first time.

Frequently asked questions

What is Superpowers?

It is a development methodology for coding assistants, maintained by obra under the MIT licence. It is made of composable skills, each in a folder with a SKILL.md file, that activate on their own in the situations they describe: design, planning, writing tests, debugging, review.

Which skills are worth knowing first?

The ones that correct a typical mistake: test-driven-development, systematic-debugging and verification-before-completion. The first enforces the test before the code, the second the search for the cause before the fix, the third the proof before declaring a piece of work done.

Can I write a skill of my own?

Yes: it is a folder with a SKILL.md file under .claude/skills/<name>/ in the project or under ~/.claude/skills/<name>/ for all your projects, as the Claude Code documentation says. You need at least a name and a description that says when to use it.

Does Superpowers work outside Claude Code?

Yes: the README lists installation also for Codex, Cursor, Gemini CLI, GitHub Copilot CLI and other environments. The instructions on this page, however, only concern Claude Code.

What you can do now

You know that Superpowers is a method installed as a plugin and not a folder to clone, and you can list its real skills without inventing new ones. You can read a skill description and recognise whether it says when to use it or summarises the procedure, and you have a script to check it. You have seen the red-green cycle on a tiny case. The next step is article 02, on the way skills are loaded.

Back to the opening guide On to Get Shit Done

Sources

  • Superpowers, repository README - definition, MIT licence, installation commands, basic flow, list of skills and supported environments, accessed 2026-11-13
  • Claude Code: Skills - paths of personal and project skills, namespace of plugin skills, accessed 2026-11-13
  • Agent Skills: specification - recommendation on the size of the SKILL.md body, accessed 2026-11-13: description of at most 1,024 characters that says what it does and when to use it, body under 500 lines and under 5,000 tokens
  • Measurements in the repository: python3 -I lint_descrizioni.py and bash tdd_run.sh on test files, locally installed Superpowers 5.1.0 plugin, each run twice with identical output, 2026-11-13

Try These Tools

Free developer tools related to this topic.

Commenti

Caricamento commenti...

Sign in to comment

New articles and tools on Telegram too

The Telegram channel flags the site's new articles and tools.

Did you like this article?

Explore other content on the blog or discover my projects