Superpowers Using

Superpowers-Using — Skill Preflight Gate

Iron rule for any task: if a relevant skill exists, you must invoke it BEFORE any response — including clarifying questions. This is the discipline layer that makes other skills actually fire.

When to Use

• ALWAYS at the start of a new task, before any other action
• After receiving an out-of-band user message mid-task
• Before responding to "what should I do about X" type questions

The Iron Rule

If a skill applies to your task, you do not have a choice. You must use it.

Source: obra/superpowers HEAD 44c9b2d6, skills/using-superpowers/SKILL.md:11-15:

"If you think there is even a 1% chance a skill might apply to what you are doing, you ABSOLUTELY MUST invoke the skill. ... This is not negotiable. You cannot rationalize your way out of this."

The Check (5 steps, takes ~2 seconds)

1. Skill preflight

skills_list()  # returns the index of all skills; descriptions truncated to 57 chars

Scan for any skill whose first 57 chars match the task shape. If even one looks relevant, run skill_view(name) and follow it.

2. Wiki preflight (only if skills miss)

read_file("~/hermes-wiki/SCHEMA.md")
read_file("~/hermes-wiki/index.md")
search_files("<key terms>", path="~/hermes-wiki", file_glob="*.md")

If a concepts/<topic>.md or projects/<name>/<topic>.md page covers this, cite it (Based on [[concepts/x]] ...) and answer from there. Don't re-research.

3. Announce

Print before any action: Using <skill-name> to <purpose>. One line. Then follow the skill. If you later find the skill doesn't fit, you can drop it — but you started from the skill, not from a guess.

4. Skill priority

When multiple skills apply, process skills come FIRST (they set the approach), then implementation skills:

• "Let's build X" → plan (or superpowers:brainstorming equivalent) FIRST, then implementation
• "Fix this bug" → systematic-debugging FIRST, then domain
• "Write tests for Y" → test-driven-development FIRST, then code
• "Add a feature" → plan (or superpowers:writing-plans equivalent) FIRST, then code
• "Add a new skill" → skill-craft-tdd FIRST, then skill_manage(action="create")

5. If nothing applies

If skills_list() and the wiki preflight both miss, you are at the boundary of known territory. Stop and either:

• (preferred) load learning-loop — it walks you through the research → skill synthesis loop
• (only if user clearly wants a one-off answer) answer from your own reasoning and DO NOT file a wiki page for trivia

Red Flags — STOP and Re-Check

If you catch yourself with any of these thoughts, you skipped a skill. Go back to step 1:

• "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. Re-read with skill_view if it has been more than a day.
• "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.

Source: obra/superpowers/skills/using-superpowers/SKILL.md:34-50.

Worked Example

User: "Add a /healthz endpoint to my FastAPI service."

1. skills_list() → scan descriptions, see "plan" (Use when... 5+ step tasks) and "test-driven-development" (TDD: enforce RED-GREEN...)
2. Process skill: plan → "Yes, this is a multi-step task, design first"
3. Implementation skill: test-driven-development → "Yes, this is a new endpoint"
4. Announce: "Using plan to design the /healthz endpoint and test-driven-development to implement it with tests-first."
5. Follow plan first, then TDD.

Common Pitfalls

1. "I already know how to do this" — the skill is the discipline layer. Loading it costs ~500 tokens; skipping it costs a redo.
2. "Skill check is overhead" — skills_list() is fast. The discipline is the value, not the lookup.
3. Wrong skill priority — implementation skills before process skills → the implementation runs before the design is sound.
4. Announcing then not following — saying "using TDD" then writing code before the test. Follow the skill, not the label.
5. Skipping the wiki preflight on retry — second-time tasks still need the wiki check. Pages get stale; re-read.

Verification Checklist

• skills_list() ran before any other action
• At least one matching skill loaded with skill_view
• "Using to " announced
• Process skill loaded before any implementation skill
• If no skill applies: learning-loop loaded or explicit user-confirmed one-off
• Wiki preflight ran if skills miss (SCHEMA + index + targeted search)