This page is a full reference for the using-superpowers skill — the bootstrap meta-skill that governs how an agent discovers and applies all other skills. It covers the mandatory invocation protocol, the 1% rule, skill type priority ordering, the Red Flags rationalization list, TodoWrite checklist integration, and the EnterPlanMode brainstorming gate.
For how skills are discovered on disk and loaded via the Skill tool, see Skills Discovery and Resolution. For how using-superpowers is injected into the agent's context at session start, see Session Lifecycle and Bootstrap. For the general skill format and authoring guide, see SKILL.md Format and Structure.
using-superpowers is the first skill an agent encounters in any session. Rather than guiding the agent through a specific task, it establishes the rules for using all other skills. Its content is injected directly into the session context via the SessionStart hook rather than being loaded on-demand like other skills.
The skill lives at skills/using-superpowers/SKILL.md
Sources: skills/using-superpowers/SKILL.md1-6 hooks/session-start17-35
Unlike other skills (which are loaded on demand via the Skill tool), using-superpowers is read and embedded directly into the system context at the start of every session.
Injection path for Claude Code and Cursor:
Diagram: Session-Start Injection Pipeline
Sources: hooks/hooks.json1-16 hooks/run-hook.cmd42-46 hooks/session-start17-35
The session-start script reads the skill file with cat "${PLUGIN_ROOT}/skills/using-superpowers/SKILL.md", escapes it for JSON embedding using the escape_for_json() function, and wraps it in an <EXTREMELY_IMPORTANT> block before emitting it as both additional_context and hookSpecificOutput.additionalContext.
Sources: hooks/session-start17-49
The core rule established by using-superpowers is:
Invoke relevant or requested skills BEFORE any response or action.
The threshold for invocation is deliberately low:
Sources: skills/using-superpowers/SKILL.md6-24
Diagram: Skill Invocation Decision Flow (mirrors skill_flow digraph)
Sources: skills/using-superpowers/SKILL.md26-53
The About to EnterPlanMode? branch enforces the brainstorming gate: if the agent is about to enter plan mode and the current task has not yet been through brainstorming, it must invoke the brainstorming skill first.
The flow diagram includes a distinct branch for EnterPlanMode:
| Condition | Action |
|---|---|
| About to enter plan mode, brainstorming already done | Proceed to normal skill check |
| About to enter plan mode, no prior brainstorming | Must invoke brainstorming skill first |
This gate prevents the agent from jumping directly into implementation planning without first validating design decisions. The brainstorming skill itself contains a <HARD-GATE> that blocks all implementation actions until the user approves a design. See brainstorming for detail on that gate.
Sources: skills/using-superpowers/SKILL.md29-42 skills/brainstorming/SKILL.md14-16
When multiple skills could apply, using-superpowers specifies a priority ordering:
| Priority | Skill Type | Examples | Role |
|---|---|---|---|
| 1 (first) | Process skills | brainstorming, systematic-debugging | Determine HOW to approach the task |
| 2 (second) | Implementation skills | frontend-design, mcp-builder | Guide execution within that approach |
Examples:
brainstorming first, then implementation skills.systematic-debugging first, then domain-specific skills.Sources: skills/using-superpowers/SKILL.md76-83
The meta-skill classifies all skills into two execution modes:
| Type | Behavior | Examples |
|---|---|---|
| Rigid | Follow exactly. Do not adapt away from the discipline. | test-driven-development, systematic-debugging |
| Flexible | Adapt principles to context. | Pattern and reference skills |
The individual skill file itself declares which mode it requires.
Sources: skills/using-superpowers/SKILL.md86-91
When a skill contains a checklist, the agent must:
TodoWrite todo item for each checklist entry.This converts the skill's written checklist into tracked, auditable task state. Skills like brainstorming have explicit numbered checklists that map directly to TodoWrite items. See Subagent-Driven Development for how TodoWrite is used across longer workflows.
Sources: skills/using-superpowers/SKILL.md47-51 skills/brainstorming/SKILL.md23-31
After invoking a skill and before executing it, the agent must announce:
Using [skill-name] to [purpose]
This makes skill usage visible in the conversation, aids debugging, and confirms to the user which workflow is active.
Sources: skills/using-superpowers/SKILL.md47-48
The meta-skill includes a table of internal thoughts that indicate the agent is about to skip a skill check illegitimately. Each maps a rationalization to the correct interpretation:
| 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. |
Sources: skills/using-superpowers/SKILL.md57-73
The meta-skill draws a distinction between user instructions (WHAT) and skill workflows (HOW):
Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.
A user saying "add a login page" does not bypass the brainstorming gate. A user saying "fix this crash" does not bypass systematic-debugging. The instruction specifies the goal; the skill specifies the procedure.
Sources: skills/using-superpowers/SKILL.md94-96
Diagram: using-superpowers Code Entities
Sources: skills/using-superpowers/SKILL.md1-96 hooks/session-start1-51 hooks/hooks.json1-16 hooks/run-hook.cmd1-46
Refresh this wiki
This wiki was recently refreshed. Please wait 3 days to refresh again.