diff --git a/skills/using-superpowers/SKILL.md b/skills/using-superpowers/SKILL.md index 53712217..de02e916 100644 --- a/skills/using-superpowers/SKILL.md +++ b/skills/using-superpowers/SKILL.md @@ -12,72 +12,23 @@ If you think there is even a 1% chance a skill might apply to what you are doing IF A SKILL APPLIES TO YOUR TASK, YOU DO NOT HAVE A CHOICE. YOU MUST USE IT. -This is not negotiable. This is not optional. You cannot rationalize your way out of this. +This is not negotiable. You cannot rationalize your way out of this. -## Instruction Priority - -Superpowers skills override default system prompt behavior, but **user instructions always take precedence**: - -1. **User's explicit instructions** (CLAUDE.md, GEMINI.md, AGENTS.md, direct requests) — highest priority -2. **Superpowers skills** — override default system behavior where they conflict -3. **Default system prompt** — lowest priority - -If CLAUDE.md, GEMINI.md, or AGENTS.md says "don't use TDD" and a skill says "always use TDD," follow the user's instructions. The user is in control. - -## How to Access Skills - -**Never read skill files manually with file tools** — always use your platform's skill-loading mechanism so the skill is properly activated. - -**In Claude Code:** Use the `Skill` tool. When you invoke a skill, its content is loaded and presented to you — follow it directly. - -**In Codex:** Skills load natively. Follow the instructions presented when a skill activates. - -**In Copilot CLI:** Use the `skill` tool. Skills are auto-discovered from installed plugins. - -**In Gemini CLI:** Skills activate via the `activate_skill` tool. Gemini loads skill metadata at session start and activates the full content on demand. - -**In other environments:** Check your platform's documentation for how skills are loaded. - -## Platform Adaptation - -Skills speak in actions ("dispatch a subagent", "create a todo", "read a file") rather than naming any one runtime's tools. For per-platform tool equivalents and instructions-file conventions, see [claude-code-tools.md](references/claude-code-tools.md), [codex-tools.md](references/codex-tools.md), [copilot-tools.md](references/copilot-tools.md), [gemini-tools.md](references/gemini-tools.md), [pi-tools.md](references/pi-tools.md), and [antigravity-tools.md](references/antigravity-tools.md). Gemini CLI users get the tool mapping loaded automatically via GEMINI.md. - -# Using Skills - ## The Rule -**Invoke relevant or requested skills BEFORE any response or action.** Even a 1% chance a skill might apply means that you should invoke the skill to check. If an invoked skill turns out to be wrong for the situation, you don't need to use it. +**Invoke relevant or requested skills BEFORE any response or action** — including clarifying questions, exploring the codebase, or checking files. Even a 1% chance a skill applies means you invoke it to check. If it turns out wrong for the situation, you don't have to use it. -```dot -digraph skill_flow { - "User message received" [shape=doublecircle]; - "About to enter plan mode?" [shape=doublecircle]; - "Already brainstormed?" [shape=diamond]; - "Invoke brainstorming skill" [shape=box]; - "Might any skill apply?" [shape=diamond]; - "Invoke the skill" [shape=box]; - "Announce: 'Using [skill] to [purpose]'" [shape=box]; - "Has checklist?" [shape=diamond]; - "Create a todo per item" [shape=box]; - "Follow skill exactly" [shape=box]; - "Respond (including clarifications)" [shape=doublecircle]; +**Before entering plan mode:** if you haven't already brainstormed, invoke the brainstorming skill first. - "About to enter plan mode?" -> "Already brainstormed?"; - "Already brainstormed?" -> "Invoke brainstorming skill" [label="no"]; - "Already brainstormed?" -> "Might any skill apply?" [label="yes"]; - "Invoke brainstorming skill" -> "Might any skill apply?"; +Then announce "Using [skill] to [purpose]" and follow the skill exactly. If it has a checklist, create a todo per item. - "User message received" -> "Might any skill apply?"; - "Might any skill apply?" -> "Invoke the skill" [label="yes, even 1%"]; - "Might any skill apply?" -> "Respond (including clarifications)" [label="definitely not"]; - "Invoke the skill" -> "Announce: 'Using [skill] to [purpose]'"; - "Announce: 'Using [skill] to [purpose]'" -> "Has checklist?"; - "Has checklist?" -> "Create a todo per item" [label="yes"]; - "Has checklist?" -> "Follow skill exactly" [label="no"]; - "Create a todo per item" -> "Follow skill exactly"; -} -``` +## Skill Priority + +When multiple skills apply, process skills come first — they set the approach, then implementation skills (frontend-design, etc.) carry it out. Brainstorming and systematic-debugging are the most common process skills, but the rule holds for any of them. + +- "Let's build X" → brainstorming first, then implementation skills. +- "Fix this bug" → systematic-debugging first, then domain skills. ## Red Flags @@ -98,24 +49,17 @@ These thoughts mean STOP—you're rationalizing: | "This feels productive" | Undisciplined action wastes time. Skills prevent this. | | "I know what that means" | Knowing the concept ≠ using the skill. Invoke it. | -## Skill Priority +## Platform Adaptation -When multiple skills could apply, use this order: +Skills name actions ("dispatch a subagent", "create a todo", "read a file"), not any one runtime's tools. For your harness's tool equivalents and instructions-file conventions, read the matching file: -1. **Process skills first** (brainstorming, systematic-debugging) - these determine HOW to approach the task -2. **Implementation skills second** (frontend-design, mcp-builder) - these guide execution - -"Let's build X" → brainstorming first, then implementation skills. -"Fix this bug" → systematic-debugging first, then domain-specific skills. - -## Skill Types - -**Rigid** (TDD, systematic-debugging): Follow exactly. Don't adapt away discipline. - -**Flexible** (patterns): Adapt principles to context. - -The skill itself tells you which. +- Claude Code: `references/claude-code-tools.md` +- Codex: `references/codex-tools.md` +- Copilot CLI: `references/copilot-tools.md` +- Gemini CLI: `references/gemini-tools.md` (also auto-loaded via GEMINI.md) +- Pi: `references/pi-tools.md` +- Antigravity: `references/antigravity-tools.md` ## User Instructions -Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows. +User instructions (CLAUDE.md, GEMINI.md, AGENTS.md, direct requests) take precedence over skills, which in turn override default system behavior. But they set WHAT to do, not HOW — "Add X" or "Fix Y" is not permission to skip the workflow a skill prescribes.