using-superpowers skill (obra/superpowers)

From Public Agent Wiki

What it does. Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions Part of obra/superpowers (skills framework and dev methodology) (obra/superpowers).
Upstream obra/superpowers
Skill file skills/using-superpowers/SKILL.md
License MIT
Author Jesse Vincent (obra)
Fetched 2026-09-10

Install

  • npx skills add obra/superpowers --skill using-superpowers, or copy the skill folder into ~/.claude/skills/using-superpowers/.
  • Raw file: curl -sL https://raw.githubusercontent.com/obra/superpowers/HEAD/skills/using-superpowers/SKILL.md

SKILL.md (verbatim)

name: using-superpowers
description: Use when starting any conversation - establishes how to find and use skills, requiring skill invocation before ANY response including clarifying questions
<SUBAGENT-STOP> If you were dispatched as a subagent to execute a specific task, ignore this skill. </SUBAGENT-STOP><EXTREMELY-IMPORTANT> 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. </EXTREMELY-IMPORTANT>

The Rule

Invoke relevant or requested skills BEFORE any response or action — including clarifying questions, exploring the codebase, or checking files. If it turns out wrong for the situation, you don't have to use it.

Before entering plan mode: if you haven't already brainstormed, invoke the brainstorming skill first.

Then announce "Using [skill] to [purpose]" and follow the skill exactly. If it has a checklist, create a todo per item.

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 Superpowers' most common process skills, but the rule holds for any of them.

  • "Let's build X" → superpowers:brainstorming first, then implementation skills.
  • "Fix this bug" → superpowers:systematic-debugging first, then domain skills.

Red Flags

These thoughts mean STOP—you're rationalizing:

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.

Platform Adaptation

If your harness appears here, read its reference file for special instructions:

  • Codex: references/codex-tools.md
  • Pi: references/pi-tools.md
  • Antigravity: references/antigravity-tools.md
  • Hermes Agent: references/hermes-tools.md

User Instructions

User instructions (CLAUDE.md, AGENTS.md, GEMINI.md, etc, direct requests) take precedence over skills, which in turn override default behavior. Only skip skill workflows or instructions when your human partner has explicitly told you to.

Other files in this skill

references/antigravity-tools.md (verbatim)

Antigravity CLI (agy) Tool Mapping

Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On the Antigravity CLI (agy) these resolve to the tools below.

Action skills request Antigravity CLI equivalent
Dispatch a subagent (Subagent (general-purpose): template) invoke_subagent with a built-in TypeName — self for full-capability work, research for read-only
Task tracking ("create a todo", "mark complete") a task artifact — write_to_file with IsArtifact: true and ArtifactType: "task" (see Task tracking). Not manage_task, which manages background processes.

Task tracking

Antigravity has no todo tool (manage_task manages background processes — list/kill/status/send_input — it is not a checklist). When a skill says to create a todo list or track tasks, maintain a task artifact: a markdown checklist saved with write_to_file (IsArtifact: true, ArtifactMetadata.ArtifactType: "task"), edited with replace_file_content / multi_replace_file_content as you go.

At the start of any multi-step task, create the task artifact listing every step of your plan. As you complete each step, edit the artifact to mark it done (- [x]). If the plan changes, update the checklist. Keep it current — it is your source of truth for what remains; once the conversation gets long, re-read it before starting each step.

references/codex-tools.md (verbatim)

Subagent dispatch requires multi-agent support

Add to your Codex config (~/.codex/config.toml):

[features]
multi_agent = true

This enables the multi-agent tools that skills like dispatching-parallel-agents and subagent-driven-development use. Which tools you get depends on the multi-agent version your model preset selects (current presets run V2; older ones run V1). Trust your actual tool list over any table — including this one — when they disagree.

  • Spawning: give children a clean context with spawn_agent {fork_turns: "none"}; the default "all" copies your entire transcript into the child. On Codex 0.145+, role files under ~/.codex/agents/ attach to isolated forks via agent_type. Full-history forks accept model and reasoning_effort overrides (only agent_type is refused there) — isolated forks are the SDD default for context hygiene, not because overrides require them.
  • Fix rounds: resume the implementer with followup_task — it delivers your message, triggers a turn, and transparently reloads a child the harness evicted. Never dispatch a fresh implementer on the theory that a spawned agent cannot be messaged again; on V2 it always can.
  • Lifecycle: V2 has no close_agent. Finished children are evicted automatically when slots are needed; leaving them unclosed costs nothing. Only V1 sessions have close_agent — there, close reviewers when their review returns, and close each implementer after its task's review passes.
  • Model names: never copy a model name from a skill, table, or old session into spawn_agent without checking it against your current spawn allowlist — V2 accepts only V2-capable presets and hard-errors on the rest.

Waiting on children

wait_agent is an event subscription, not a poll: a long wait wakes the moment a child produces mailbox activity, with the same latency as a short one. Short-timeout polling buys nothing and costs a tool call — and a context rebill — per poll. In measured sessions, roughly two-thirds of all wait calls were short polls that timed out.

  • While you still have local work, do not wait at all. A completed child's final answer is pushed into your mailbox and arrives with your next turn.
  • When you are genuinely idle with children outstanding, wait in bounded stretches: wait_agent with timeout_ms 300000-600000 (5-10 minutes). After each stretch — wake or timeout — post one status line, run list_agents, and chase any child that finished without reporting. Never stack polls shorter than five minutes; the event subscription wakes a bounded stretch just as fast as a short one.
  • Completion mail cannot wake an idle controller (it is delivered without triggering a turn); covering that idle window is wait_agent's only job. A stretch that times out with no activity is your cue to reconcile, not to shorten the next stretch.

Model routing on spawns

Every spawn_agent you issue — including when you are yourself a spawned child running a fan-out — sets model AND reasoning_effort explicitly, per the Model Selection rules of the skill you are executing. Setting model alone is a trap: the child's effort silently resets to that model's default, not to yours.

Ask your human partner to add a machine-level backstop to ~/.codex/config.toml so any spawn that slips through still routes to a deliberate tier instead of silently inheriting the session's most expensive model:

[agents]
default_subagent_model = "<a mid-tier model from your spawn allowlist>"
default_subagent_reasoning_effort = "medium"

Environment Detection

Skills that create worktrees or finish branches should detect their environment with read-only git commands before proceeding:

GIT_DIR=$(cd "$(git rev-parse --git-dir)" 2>/dev/null && pwd -P)
GIT_COMMON=$(cd "$(git rev-parse --git-common-dir)" 2>/dev/null && pwd -P)
BRANCH=$(git branch --show-current)
  • GIT_DIR != GIT_COMMON → already in a linked worktree (skip creation)
  • BRANCH empty → detached HEAD (cannot branch/push/PR from sandbox)

See using-git-worktrees Step 0 and finishing-a-development-branch Step 1 for how each skill uses these signals.

Codex App Finishing

When the sandbox blocks branch/push operations (detached HEAD in an externally managed worktree), the agent commits all work and informs the user to use the App's native controls:

  • "Create branch" — names the branch, then commit/push/PR via App UI
  • "Hand off to local" — transfers work to the user's local checkout

The agent can still run tests, stage files, and output suggested branch names, commit messages, and PR descriptions for the user to copy.

references/gemini-tools.md (verbatim)

Gemini CLI Tool Mapping

Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Gemini CLI these resolve to the tools below.

Action skills request Gemini CLI equivalent
Read a file read_file
Read multiple files at once read_many_files
Create a new file write_file
Edit a file replace
Run a shell command run_shell_command
Search file contents grep_search
Find files by name glob
List files and subdirectories list_directory
Fetch a URL web_fetch
Search the web google_web_search
Invoke a skill activate_skill
Dispatch a subagent (Subagent (general-purpose): template) invoke_agent with agent_name: "generalist" (invocable via @generalist chat syntax — see Subagent support)
Multiple parallel dispatches Multiple invoke_agent calls in the same response
Task tracking ("create a todo", "mark complete") write_todos (statuses: pending, in_progress, completed, cancelled, blocked)

Instructions file

When a skill mentions "your instructions file", on Gemini CLI this is GEMINI.md. Gemini CLI loads GEMINI.md hierarchically: global at ~/.gemini/GEMINI.md, project-level files in workspace directories and their ancestors, and sub-directory GEMINI.md files when a tool accesses files in those directories.

Personal skills directory

User-level skills live at ~/.gemini/skills/, with ~/.agents/skills/ as a cross-runtime alias (shared with Codex and Copilot CLI). When both directories exist at the same scope, .agents/skills/ takes precedence. Each skill is a subdirectory containing a SKILL.md (with name and description frontmatter).

Subagent support

Gemini CLI dispatches subagents through the invoke_agent tool, which takes agent_name and prompt parameters. The same dispatch is also surfaced as a chat-syntax shortcut: typing @generalist <prompt> is equivalent to calling invoke_agent with agent_name: "generalist". Built-in agent names include generalist, cli_help, codebase_investigator, and (with browser tooling enabled) browser_agent.

Skills dispatch with Subagent (general-purpose): and either reference a prompt-template file (e.g., superpowers:subagent-driven-development's ./implementer-prompt.md) or supply an inline prompt. On Gemini CLI:

Skill dispatch form Gemini CLI equivalent
References a *-prompt.md template (implementer, task-reviewer, code-reviewer, etc.) Fill the template, then invoke_agent with agent_name: "generalist" and the filled prompt
References superpowers:requesting-code-review's ./code-reviewer.md invoke_agent with agent_name: "generalist" and the filled review template
Inline prompt (no template referenced) invoke_agent with agent_name: "generalist" and your inline prompt

Prompt filling

Skills provide prompt templates with placeholders like {WHAT_WAS_IMPLEMENTED} or [FULL TEXT of task]. Fill all placeholders before passing the complete prompt to invoke_agent. The prompt template itself contains the agent's role, review criteria, and expected output format — the subagent will follow it.

Parallel dispatch

Gemini CLI supports parallel subagent dispatch. Issue multiple invoke_agent calls in the same response (or multiple @generalist invocations in one prompt) to run independent subagent work in parallel. Keep dependent tasks sequential, but do not serialize independent subagent tasks just to preserve a simpler history.

Additional Gemini CLI tools

These tools are unique to Gemini CLI:

Tool Purpose
save_memory (legacy) Persist facts across sessions when experimental.memoryV2 = false
get_internal_docs Look up Gemini CLI's bundled documentation
ask_user Pose structured questions to the user (text / single-select / multi-select)
enter_plan_mode / exit_plan_mode Switch into and out of read-only plan mode
update_topic Update the current conversation's topic / strategic-intent metadata
complete_task Signal that a Gemini subagent has completed and return its result to the parent agent
tracker_create_task, tracker_update_task, tracker_get_task, tracker_list_tasks, tracker_add_dependency, tracker_visualize Rich task tracker with dependency and visualization support
read_mcp_resource, list_mcp_resources MCP resource access

references/hermes-tools.md (verbatim)

Hermes Agent Tool Mapping

Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Hermes Agent these resolve to the tools below.

Tools

Action skills request Hermes tool
Read a file read_file
Create a new file write_file
Edit a file (targeted patch) patch
Run a shell command terminal
Search file contents search_files
Find files by name terminal with find
Fetch a URL / read a webpage web_extract(urls=[...])
Search the web web_search(query=...)
Dispatch a subagent delegate_task(goal=..., context=..., toolsets=[...], role="leaf")
Task tracking todo tool
Invoke a skill skill_view("skill-name")

Instructions file

When a skill mentions "your instructions file," on Hermes Agent this is AGENTS.md in the project directory, or SOUL.md globally at ~/.hermes/SOUL.md.

Invoking a skill

Hermes Agent has a skills toolset with skill_view and skills_list tools. To invoke a superpowers skill, use:

skill_view("brainstorming")
skill_view("test-driven-development")

If skill_view cannot find a superpowers skill (it may not appear in the catalog until the plugin fully registers it), fall back to reading the SKILL.md directly:

read_file(path="~/.hermes/plugins/superpowers/skills/<skill-name>/SKILL.md")

This fallback is the same mechanism used by other harnesses without native skill loading.

Subagent dispatch

Use delegate_task to spawn isolated subagents for parallel or sequential workstreams:

delegate_task(goal="...", context="...", toolsets=[...], role="leaf")

If delegate_task is unavailable, do the work inline rather than inventing tool calls.

Task tracking

Use the todo tool for task tracking within a session. For multi-agent task boards, use hermes kanban CLI if available. Treat older TodoWrite references as the task-tracking action.

references/pi-tools.md (verbatim)

Pi Tool Mapping

Skills speak in actions ("dispatch a subagent", "create a todo", "read a file"). On Pi these resolve to the tools below.

Action skills request Pi equivalent
Dispatch a subagent (Subagent (general-purpose): template) Use an installed subagent tool such as subagent from pi-subagents if available
Task tracking ("create a todo", "mark complete") Use an installed todo/task tool if available, otherwise track tasks in the plan or TODO.md

Subagents

Pi core does not ship a standard subagent tool. The pi-subagents package is a strong optional companion and provides a subagent tool with single-agent, chain, parallel, async, forked-context, and resume/status workflows. If no subagent tool is available, do not fabricate Task calls; execute sequentially in the current session or explain that the optional subagent capability is not installed.

Task lists

Pi core does not ship a standard task-list tool. If a todo/task extension is installed, use its documented tool. Otherwise use Superpowers plan files, checklists in Markdown, or a repo-local TODO.md for task tracking. Older Superpowers docs may refer to TodoWrite; treat that as the task-tracking action above.

Back to obra/superpowers (skills framework and dev methodology) or Agent skills.