rogee/superpowers
1
0
Fork 0
mirror of https://github.com/obra/superpowers.git synced 2026-06-25 20:19:04 +08:00
Code Issues Packages Projects Releases Wiki Activity

WIP snapshot: compress using-superpowers bootstrap (~1698 → ~993 tokens)

Browse Source 
Condense the injected bootstrap without dropping behavior-shaping content:
replace the graphviz flowchart with prose (1% rule, plan-mode->brainstorm gate,
announce + checklist->todos), fold Instruction-Priority into User Instructions,
and drop the per-platform skill-loading section. Keep the full Red Flags
rationalization table (all 12), the platform tool-mapping pointer (now a
skill-relative path list), skill priority framed as a category (process before
implementation, not just the two named skills), and user-instruction precedence
plus the WHAT/HOW guard.

Snapshot on a local branch for review — NOT final, NOT for dev. Open items:
the dropped "Skill Types" (rigid/flexible) section, and evals for user
preferences overriding skills. Clean Docker evals show the more-aggressive
g-minimal preserves load-bearing triggering across opus/sonnet/haiku/codex/
gemini/kimi; this variant keeps more content.

Claude-Session: https://claude.ai/code/session_01Hz32pBE7kiqr78DY6PWmZN
This commit is contained in:
Jesse Vincent
2026-06-23 11:08:17 -07:00
parent 321c8cd24c
commit 274cf1617b
1 changed files with 19 additions and 75 deletions
Download Patch File Download Diff File Expand all files Collapse all files

94
skills/using-superpowers/SKILL.md
View File

@@ -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.
</EXTREMELY-IMPORTANT>
## 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.