Install superpowers and the next Claude Code session already contains its rule, before you type a word. The file is 465 words. It does not arrive through the skill picker. A SessionStart hook reads it and pastes it into the session, so the model does not get to decide whether the instruction applies. On skills.pub the same file is using-superpowers, version 7.0.2 from a repository with 322,125 stars.
What does the SKILL.md actually contain?
Only instructions about choosing skills. It has no tool definitions, no scripts, and no domain knowledge. Five headings, two XML blocks, 465 words.
| Part | What it says | Why it matters |
|---|---|---|
<EXTREMELY-IMPORTANT> block |
"You have superpowers" framing that precedes the headings | Reaches the model before the rules, so it reads as a system-level note |
## The Rule |
Invoke a skill if there is even a 1% chance one applies | Converts "should I use a skill" into a near-certain yes |
## Skill Priority |
Process skills first, then implementation skills | Fixes the ordering problem where an agent starts coding before planning |
## Red Flags |
13-row table of rationalisation vs. refutation | Pre-empts the model's own excuses for skipping the rule |
## Platform Adaptation |
Points at per-harness references/*-tools.md
|
One file serves Claude Code, Codex, Gemini, Muse and others |
The Red Flags table is the unusual part. Each row names an excuse a model might generate ("this is too simple to need a skill") next to the counter-argument. That is a prompt pattern aimed at a specific behaviour, not general advice.
How does it get into the session?
Through a hook, not through invocation. The repository ships hooks/hooks.json:
{"hooks":{"SessionStart":[{"matcher":"startup|clear|compact","hooks":[{"type":"command",
"command":"\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",
"shell":"bash","async":false}]}]}}
The matcher fires on startup, clear, and compact — so the rule also comes back after a context compaction, which is exactly when an agent tends to forget its instructions. hooks/session-start reads SKILL.md with the shell read builtin and JSON-escapes it into the session, emitting one of four envelopes depending on whether CURSOR_PLUGIN_ROOT, CLAUDE_PLUGIN_ROOT, MUSE_PLUGIN_ROOT, or COPILOT_CLI is set. The script's comments explain the choice of builtin: a cat or a subshell costs tens of milliseconds under Git Bash on Windows, and this runs at every session start.
| Question | Answer |
|---|---|
| Does the model choose to load it? | No. The hook injects it every session. |
| Does it need network access? | No. No URLs, no npx, no Python. |
| Does it need anything installed? |
bash (or zsh), plus the directory in CLAUDE_PLUGIN_ROOT. |
| What breaks it? | A harness that does not run plugin SessionStart hooks. |
What happens after the injection?
The first instruction is not to work — it is to look up a skill. ## The Rule requires invoking the relevant skill before any response, "including clarifying questions, exploring the codebase, or checking files". Then it asks the model to announce Using [skill] to [purpose] and follow that skill's checklist, creating a todo per item.
It also sets an ordering rule you can watch for: "Let's build X" resolves to superpowers:brainstorming first, not to an implementation skill. ## Skill Priority states that process skills come first because they set the approach, and only then do implementation skills apply. The repository ships 15 skills in skills/, and brainstorming is the entry point for new work.
There is a precedence rule worth knowing before you install it: user instructions in CLAUDE.md, AGENTS.md, or a direct request take precedence over the skill. So the injection redirects the model's default behaviour without overriding your project instructions.
Does the hook override the model's own judgement?
It biases it heavily, and the file is honest about that. "If you think there is even a 1% chance a skill might apply" is not a heuristic a model can satisfy by reasoning; it is a near-mandatory gate. The Red Flags table then closes the escape routes the model would otherwise use.
The failure mode to expect is over-invocation, not under-invocation. A session that starts with a one-line question may still open a skill and a todo list before answering. ## User Instructions is the intended brake: a direct request that says to answer briefly should win, because the file says user instructions take precedence.
Installation, and one discrepancy worth knowing
skills.pub lists the install command as /plugin marketplace add obra-superpowers, which matches the in-repo .claude-plugin/marketplace.json — but that manifest is named superpowers-dev and points at "./". It is the development marketplace. The repository README sends users to two other routes:
| Route | Command | What you get |
|---|---|---|
| Official marketplace | /plugin install superpowers@claude-plugins-official |
The published plugin |
| Author's marketplace |
/plugin marketplace add obra/superpowers-marketplace then /plugin install superpowers@superpowers-marketplace
|
The author's own release channel |
| In-repo (dev) | /plugin marketplace add obra-superpowers |
Version 7.0.2 from the working tree |
If you follow the in-repo route you are installing the development copy, which is what the directory indexes. That is not wrong — it is the same commit — but the version you get is tied to the repository's main, not to the published plugin's release cadence.
What to check before you keep it installed
Three things, each observable in the first session:
- Start a new session and ask a question with an obvious skill match. The announcement line
Using [skill] to [purpose]should appear before any other work. - Run
/clearand ask again. The rule should still be present, because the hook matchesclear. - Ask something that needs no skill. If the model still opens one, raise the specificity of your request — the file defers to user instructions.
The claims above about file contents and hook configuration come from the repository at main on 2026-11-20: the SKILL.md, the hook config, and the session-start script. The runtime behaviour is read from that source and its tests, not from a recorded Claude Code session.
Originally published at skills.pub.
Top comments (0)