Superpowers: The Anatomy of an Agent Skill
Anyone who has spent time pair-programming with an LLM has felt the same<br>small betrayal: you write a clear instruction in your CLAUDE.md, watch the<br>agent acknowledge it, and then watch it cheerfully ignore the instruction<br>twenty minutes later. The system prompt is not a contract. It is a suggestion<br>the model weighs against everything else in its context.
Superpowers, created by<br>Jesse Vincent in October 2025, was not the first structured attempt to<br>make agents behave - Cursor's rules files and CLAUDE.md<br>conventions came earlier - but it is one of the most widely-adopted and<br>thoroughly worked-out. It is an installable plugin - the author calls it<br>"an agentic skills framework and software development methodology" - that<br>bundles fourteen "skills" (small markdown files encoding a development<br>methodology) with a bootstrap mechanism that forces the agent to consult<br>them. The skills are the visible part; the bootstrap is what turns inert<br>files into a framework. In seven months it has crossed 200,000 stars on<br>GitHub.
200k+GitHub stars
14shipped skills
7months old
6+agent platforms
The interesting part is not that Superpowers exists. It is why it<br>works. Each design choice - the frontmatter shape, the bootstrap hook, the<br>sentence that opens every description, the bright-red "IRON LAW" banners -<br>is a specific response to a specific failure mode the author observed in<br>agents. Read together, the codebase is a textbook on how to write<br>instructions a model will actually follow.
This explainer takes that textbook apart. We'll look at the four pieces<br>that make Superpowers' skills effective - the bootstrap, the anatomy,<br>the description rule, and the loophole-closing pattern - and end with a<br>scorecard you can apply to any skill, in any framework.
The Bootstrap Problem
Before we talk about what a great skill looks like, there is a<br>more basic question: how does the agent know to use one at all? An agent<br>that doesn't reach for a skill is exactly as useful as no skill at all,<br>and in practice agents reach for things lazily. A skill is just a markdown<br>file sitting in a directory - and a file the agent never opens is no more<br>useful than the CLAUDE.md it already ignores.
Design Choice<br>One Meta-Skill Pre-Loaded into Every Session
Superpowers solves the bootstrap with a single trick: a<br>SessionStart hook . A hook is a plugin-level<br>capability, not a skill-level one - a SKILL.md file can't<br>register anything, so this is declared by the Superpowers plugin<br>(in its hooks/hooks.json) and wired up when you install and<br>enable the plugin. From then on it fires on every session<br>startup, clear, or compact. Each<br>time it fires, a small script reads one file -<br>using-superpowers/SKILL.md - and injects its full contents<br>into the session as additional context, wrapped in<br>tags.
That meta-skill is the only one injected in full automatically. Its<br>job is to teach the agent that the Skill tool exists and<br>must be invoked aggressively. Every other skill is listed by name and<br>trigger description, but its body stays dormant on disk until the agent<br>reaches for it.
The hook registration is a few lines of JSON:
// hooks/hooks.json - shipped by the plugin, not by any skill<br>"hooks": {<br>"SessionStart": [{<br>"matcher": "startup|clear|compact",<br>"hooks": [{<br>"type": "command",<br>// run-hook.cmd is a cross-platform wrapper that execs session-start<br>"command": "\"${CLAUDE_PLUGIN_ROOT}/hooks/run-hook.cmd\" session-start",<br>"async": false<br>}]<br>}]
The animation below shows what this actually does inside a session.<br>Either way the harness lists the available skills - their names and<br>trigger descriptions are visible to the agent through the Skill tool.<br>What the bootstrap changes is propensity: with the hook off, nothing<br>pushes the agent to act on that list, so it tends to improvise unless a<br>skill is glaringly relevant. With the hook on, the meta-skill arrives<br>before the first user token and tells the agent to reach for a skill on<br>even a 1% chance it applies.
Figure 1 - Session Bootstrap
Hook:<br>Superpowers ON<br>Superpowers OFF
Replay
The SessionStart hook runs before the user's first message<br>arrives. The skills are listed in the Skill tool either<br>way - the hook doesn't make them exist, it makes the agent reliably<br>reach for them. With the hook on, using-superpowers<br>pre-loads the aggressive "invoke on a 1% chance" rule. With it off, the<br>agent can still invoke a skill but frequently skips it and improvises.
This pattern - auto-load a meta-skill that makes the agent reliably<br>reach for everything else - is the single most important design<br>decision in the framework. It separates "skills the agent could use"<br>from "skills the agent will use." The skills are discoverable without it;<br>the bootstrap is what makes them reliably used rather than quietly<br>ignored.
Anatomy of a SKILL.md
Each skill lives in skills//SKILL.md. The format<br>is deliberately spartan: a YAML frontmatter with exactly two fields, then<br>a markdown body that follows a small...