Superpowers Using Superpowers: The Bootstrap Skill That Runs Before Every Response

Every System Needs an Entry Point

A skill library is only as good as the moment an agent remembers to consult it. You can write the best debugging methodology in the world, document it perfectly, and ship it to every machine your team runs — and a capable agent will still skip it, because the task looked easy and the agent already “knew how to debug.” The superpowers using superpowers skill exists to close that gap. It is the bootstrap of the Superpowers library: a small meta-skill whose single job is to make every other skill get loaded at the right moment — before the agent says anything at all.

This article is a deep dive into how that bootstrap works: the discovery pattern it standardizes, the unusually strict rule it enforces, how it adapts across six different agent harnesses, and what a run looks like when every skill in the chain fires in order — traced through a real infrastructure audit on one of our production boxes.

What the using-superpowers Skill Actually Does

The skill triggers at the start of any conversation. Its contents establish three things and nothing else:

• How to find skills. The agent’s index shows only names and one-line descriptions; the full procedure lives inside each skill file.
• When to load them. Before any response or action — including clarifying questions, codebase exploration, and quick file checks.
• How to behave once loaded. Announce the skill, follow it exactly, and convert any checklist it contains into a todo item per line.

That is the whole design. The bootstrap carries no methodology of its own — no debugging phases, no planning templates. It is pure control flow: an interrupt handler that runs before the agent’s own reasoning gets a chance to talk itself out of doing homework.

One exemption is baked into the top of the file: a <SUBAGENT-STOP> block tells dispatched subagents to ignore the skill entirely. The orchestrator already did the routing when it wrote the subagent’s brief; making every worker re-run skill discovery would add overhead and second-guess the delegation. The bootstrap runs at the top of the control loop, not inside every leaf of it.

The Rule: Skill Check Comes Before Everything

Most agent instructions are written as guidance. This one is written as a wall, wrapped in literal <EXTREMELY-IMPORTANT> tags so it survives any amount of context pressure:

If you think there is even a 1% chance a skill might apply
to what you are doing, you ABSOLUTELY MUST invoke the skill.

IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE.
YOU MUST USE IT.

This is not negotiable. You cannot rationalize your way out
of this.

The load-bearing detail is timing. The rule requires invoking relevant skills before any response — and it explicitly enumerates the escape hatches agents reach for: asking a clarifying question, exploring the codebase, checking git, “gathering a little context first.” All of those are responses. The skill check precedes them, because skills tell you how to ask, how to explore, and what to look at. Checking files before checking skills inverts the order and quietly produces the exact unstructured flailing the library exists to prevent.

The 1% threshold is deliberate. It removes the judgment call: the agent is not asked to decide whether a skill is needed, only whether there is any plausible chance it applies. If the skill turns out to be wrong for the situation, the agent simply doesn’t have to use it — the cost of a false positive is one file read. The cost of a false negative is an undisciplined run.

The Skill Discovery Pattern

Loading a skill is one call: skill_view("superpowers-<name>"). The pattern is a two-level lookup, and it is worth understanding as a lazy-loading problem:

• Level 1 — the index. Every installed skill contributes a name plus a ~60-character description to the agent’s always-visible listing. This is cheap enough to live in every context window.
• Level 2 — on-demand load. skill_view pulls the full SKILL.md (plus its references, templates, and scripts) into context only when the skill is actually invoked.

The naming discipline matters as much as the call. The superpowers- prefix makes the library one prefix-match away, and each description is written as a trigger — “Use when starting any conversation…”, “Use when you have a spec or requirements for a multi-step task…” — so level 1 is doing pattern matching the agent barely has to think about.

After the call comes the part agents most often skip: announce, then obey. The skill says to state “Using [skill] to [purpose]” out loud and then follow it exactly — if it ships a checklist, every item becomes a todo. The announcement is not theater. It puts the commitment in the transcript, where the user can veto it and where later turns can hold the run accountable to it.

Skill Priority: Process Before Implementation

When several skills plausibly apply, the bootstrap imposes an ordering rather than leaving it to taste: process skills come first — they set the approach — and implementation skills carry it out. Two worked examples from the skill itself:

• “Let’s build X” → brainstorming first to produce an approved design, then frontend/backend/domain skills to build it.
• “Fix this bug” → systematic-debugging first to establish root cause, then domain skills for the change itself.

Without this rule, “build X” resolves straight to the implementation skill, and the design phase silently disappears — the most expensive omission in the chain, because it’s the one nobody notices until the wrong thing ships.

Why the Bootstrap Matters: Killing “I Remember This”

The deepest problem the bootstrap solves isn’t forgetting — it’s remembering. Skills are prose, and agents are fluent in prose, which means an agent that has seen a skill once believes it has internalized it. The skill ships a red-flags table specifically to name and shoot that reflex:

The “I remember this skill” row is the one that justifies the whole meta-skill. Stale mental copies drift: a skill gets a new verification step, a tightened gate, a fixed edge case, and the agent is still executing the version it read three weeks ago — confidently, and with no diff to notice. Re-invoking on every use makes skill updates take effect immediately, the same way a package manager beats copy-pasting library source into your project. The re-read costs a few hundred tokens; the stale copy costs the improvement itself.

Platform Adaptation: One Rule, Six Harnesses

The Superpowers library targets multiple agent products, and each one names its tools differently — what counts as “invoking a skill,” where todos live, how subagents get dispatched. The bootstrap handles this with a single dispatch table: if your harness appears in the list, read its reference file for special instructions:

The architecture keeps the methodology portable and confines the glue to one small file per platform. The 1% rule, the priority ordering, and the rationalization table are identical everywhere; only the mechanics of how you call skill_view, raise a todo, or spawn a subagent change per harness.

Precedence is settled at the bottom of the file: explicit user instructions (CLAUDE.md, AGENTS.md, direct requests) beat skills, which beat default behavior. The bootstrap enforces skills; it does not override the human.

Real Example: The SYNAS Audit, Skill by Skill

SYNAS is one of our always-on production boxes — Docker services behind an nftables drop-only SSH lock, the kind of machine where a confident wrong command is an outage. The request was five words: “look into Docker on SYNAS.” Here is the bootstrap’s control flow on that exact message, announce-and-all:

• Message arrives. using-superpowers is already resident from session start. It scans the index against “look into Docker on SYNAS,” finds multiple plausible matches (more than 1%?), and halts any response until a process skill is loaded. No docker ps reflex.
• “Using brainstorming to scope the audit.” skill_view on the brainstorming skill. Its checklist becomes todos; a read-only survey subagent gathers the container inventory while the dialogue pins down purpose, blast radius, and deliverable.
• “Using writing-plans to turn the approved design into a plan.” The writing-plans skill converts the approved design doc into a step-by-step plan with verification defined per step.
• “Using executing-plans to run it.” The executing-plans skill holds the run to the plan — each finding checked against its verification criterion before being reported, nothing marked done on vibes.

Two things are worth noticing. First, the handoffs were explicit: the bootstrap routed to brainstorming, and brainstorming’s own final step handed off to writing-plans. Nobody chose the sequence ad hoc; it is encoded in the skills. Second, the audit’s most valuable output is an absence: nothing restarted, nothing “cleaned up,” because the design gate approved the method before any state-changing command existed. That outcome is invisible in logs — you only see it by tracing which skill fired first.

Related Deep Dives in the Series

Here is everything using-superpowers sits above — the complete library it exists to dispatch into:

Notice the shape: every entry is a procedure for a specific moment, and the bootstrap is the router that connects a moment to its procedure. Remove the router and you don’t lose a step — you lose every step at once, because each one depends on being invoked at a moment an agent would rather improvise.

Where This Fits in the Series

This article is the entry point to the Superpowers deep-dive series, and the reading order mirrors the runtime order: the brainstorming skill is the first gate a real task hits, the writing-plans skill turns the approved design into a plan, and the executing-plans skill carries it to verified completion. Start with using-superpowers itself, though — it is the one skill that decides whether you ever reach the others.