Name: Using Superpowers
Author: obra

tl;dr: the bootstrap skill for the whole obra/superpowers system. It runs at session start and again after compaction, and its only job is to make the agent scan for skills before any action — including before clarifying questions, before exploring the codebase, and before plan mode. Without it loaded, the agent will rationalize its way past the rest of the methodology.

What it actually does

SKILL.md (obra/superpowers, fetched 2026-09-10) opens with the rule in capitals and a <SUBAGENT-STOP> carve-out:

Invoke relevant or requested skills BEFORE any response or action — including clarifying questions, exploring the codebase, or checking files. If it turns out wrong for the situation, you don’t have to use it.

Three things follow from that rule.

1. The announcement form. Before acting, the agent says “Using [skill] to [purpose]” and follows the skill exactly. If the skill has a checklist, the agent makes a todo per item. This is the public declaration that lets the operator see the methodology is engaged.

2. Skill priority. When multiple skills apply, process skills come first — they set the approach, then implementation skills carry it out. The two named examples:

“Let’s build X” → superpowers:brainstorming first, then implementation skills.
“Fix this bug” → superpowers:systematic-debugging first, then domain skills.

brainstorming and systematic-debugging are flagged as the most common process skills, but the rule holds for any process skill.

3. Before plan mode specifically. If the agent is about to enter plan mode and has not yet brainstormed, brainstorming is mandatory first. Plan mode produces a plan; brainstorming decides whether the plan is solving the right problem.

The rationalization table (verbatim from SKILL.md)

The skill dedicates more space to not skipping skills than to invoking them. Verbatim:

Thought	Reality
”This is just a simple question”	Questions are tasks. Check for skills.
”I need more context first”	Skill check comes BEFORE clarifying questions.
”Let me explore the codebase first”	Skills tell you HOW to explore. Check first.
”I can check git/files quickly”	Files lack conversation context. Check for skills.
”Let me gather information first”	Skills tell you HOW to gather information.
”This doesn’t need a formal skill”	If a skill exists, use it.
”I remember this skill”	Skills evolve. Read current version.
”This doesn’t count as a task”	Action = task. Check for skills.
”The skill is overkill”	Simple things become complex. Use it.
”I’ll just do this one thing first”	Check BEFORE doing anything.
”This feels productive”	Undisciplined action wastes time. Skills prevent this.
”I know what that means”	Knowing the concept ≠ using the skill. Invoke it.

The closing principle: “Violating the letter of this rule is violating the spirit of this rule.” Same wording as verification-before-completion — these two are the two non-negotiable skills in the system.

Platform adaptation

The skill pulls in host-specific reference files when the harness is named:

Codex → references/codex-tools.md
Pi → references/pi-tools.md
Antigravity → references/antigravity-tools.md
Hermes Agent → references/hermes-tools.md

If your host is in that list and the reference file is missing, the skill will not behave correctly on that harness — that is the most common installation failure (see Gotchas).

Where it sits in the Superpowers flow

The README workflow puts using-superpowers at step zero, before brainstorming itself:

bootstrap → using-superpowers decides what’s loaded
brainstorm → brainstorming decides what to build
worktree → using-git-worktrees decides where to build it
plan → writing-plans decides how to break it up
execute → subagent-driven-development or executing-plans
review → requesting-code-review between tasks
finish → finishing-a-development-branch

Every other skill in the system assumes using-superpowers is loaded. The README explicitly says skills “trigger automatically” — that is using-superpowers doing its job.

Install

Per the upstream README, there is no npx skills add obra/superpowers command. Install is one level up (the whole plugin, not this single skill) and is per-harness:

# Claude Code — Anthropic official marketplace
/plugin install superpowers@claude-plugins-official

# Claude Code — Superpowers marketplace
/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

# Codex CLI — official marketplace
/plugins    # search "superpowers" → Install Plugin

# Cursor
/add-plugin superpowers

# Gemini CLI
gemini extensions install https://github.com/obra/superpowers

# OpenCode — host fetches its own install doc
# Say: "Fetch and follow instructions from
#       https://raw.githubusercontent.com/obra/superpowers/refs/heads/main/.opencode/INSTALL.md"

# Pi (native skills, no Skill tool needed)
pi install git:github.com/obra/superpowers

# Antigravity
agy plugin install https://github.com/obra/superpowers

# Hermes
hermes plugins install obra/superpowers --enable

The published SKILL.md only works when the surrounding skills/using-superpowers/ directory tree is present (it references references/codex-tools.md etc.). Installing just SKILL.md on its own will load but fail on platform-specific behavior.

Gotchas

SUBAGENT-STOP is not optional. If you were dispatched as a subagent to execute a specific task, this skill tells you to ignore itself. Subagents that load using-superpowers end up re-bootstrapping the whole system for a narrow task.
Compaction kills it. Hermes has no post-compaction hook — very long sessions that compact over their first turn lose the bootstrap. Start a fresh session if skills stop triggering. (Same caveat affects Claude Code in milder form.)
Per-harness install, not per-skill. Installing one SKILL.md from obra/superpowers into ~/.claude/skills/ does not load using-superpowers. The bootstrap expects the whole plugin, including the references directory it points at.
Process skills outrank implementation skills. “Let me just open VS Code” or “let me just write the migration” without systematic-debugging / brainstorming first is the failure mode the rationalization table was written to stop.
User instructions outrank skills. CLAUDE.md, AGENTS.md, GEMINI.md, and direct operator requests take precedence. Only skip skill workflows when the human partner has explicitly told you to.
The skill evolves, your memory doesn’t. The red-flag table has been rewritten at least once; reading a cached “I remember this skill” version is on the rationalization list. Re-read SKILL.md on every session if your host doesn’t auto-load it.
sandbox_test.verdict: untested — we fetched SKILL.md and the README; we did not run using-superpowers end-to-end against a real conversation in the sandbox.

Related: Brainstorming (obra/superpowers) — the process skill using-superpowers escalates to most often; Executing Plans (obra/superpowers) — the workflow that depends on the bootstrap being loaded; Verification Before Completion (obra/superpowers) — the other non-negotiable, same “violating the letter is violating the spirit” wording.

Using Superpowers

## what it does