Using Superpowers

<SUBAGENT-STOP> If you were dispatched as a subagent to execute a specific task, skip 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. This is not optional. 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, codex-tools.md, copilot-tools.md, gemini-tools.md, pi-tools.md, and 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.

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];

    "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?";

    "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";
}

Red Flags

These thoughts mean STOP—you're rationalizing:

Skill Priority

When multiple skills could apply, use this order:

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.

User Instructions

Instructions say WHAT, not HOW. "Add X" or "Fix Y" doesn't mean skip workflows.

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.

Invoking a skill — read its SKILL.md

Antigravity surfaces every installed skill's name + description to you at the start of each session, but it has no `Skill`/`activate_skill` tool. To load a skill, read its `SKILL.md` with `view_file`, setting `IsSkillFile: true` when the skill applies — e.g. view_file on .../plugins/superpowers/skills/<skill-name>/SKILL.md with IsSkillFile: true. (IsSkillFile is agy's own signal that you're reading a file to execute its instructions, not to edit or preview it — set it whenever you load a skill.)

This is the blessed skill-loading mechanism on this harness. The general rule "never read skill files manually" means "don't bypass your platform's skill-loading mechanism" — and on Antigravity, reading SKILL.md is that mechanism. Reading it honors the rule rather than breaking it.

You already know which skills exist and what they're for: their names and descriptions are in front of you at session start. When a description matches what you're about to do, read that skill's SKILL.md before acting.

Subagent support

Antigravity dispatches subagents with invoke_subagent, passing each one a TypeName in the Subagents array. Two TypeNames are built in — use them directly, no define_subagent needed:

• `self` — a full clone of you, with every tool you have (including

write_to_file/replace_file_content/run_command). The safe default for general-purpose work: implementing, fixing, anything that edits files or runs commands.

• `research` — read-only (file reading, grep_search, web/URL fetch; no write

or command access). Use it when you specifically want a subagent that can't make changes — investigation and read-only review.

Call define_subagent only for a custom system prompt or capability mix: set enable_write_tools: true to grant file edits and run_command, enable_subagent_tools for nested dispatch, enable_mcp_tools for MCP. Then invoke it by the name you gave it. (manage_subagents lists/kills running subagents.)

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 Antigravity:

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_subagent. The prompt template itself contains the agent's role, review criteria, and expected output format — the subagent will follow it.

Parallel dispatch

Put multiple entries in a single invoke_subagent call's Subagents array to run independent subagent work in parallel. Keep dependent tasks sequential, but do not serialize independent subagent tasks just to preserve a simpler history.

Task tracking

Antigravity has no todo / `TodoWrite` 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.

Claude Code Tool Mapping

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

Tools

Instructions file

When a skill mentions "your instructions file", on Claude Code this is `CLAUDE.md`. Claude Code walks up the directory tree from the current working directory and concatenates every CLAUDE.md and CLAUDE.local.md it finds along the way. Standard locations:

CLAUDE.md files can pull in additional content with @path/to/file imports (relative or absolute, max five hops deep). Subdirectory CLAUDE.md files are also discovered automatically and loaded on-demand when Claude Code reads files in those subdirectories.

Claude Code does not read AGENTS.md directly. If a project already maintains AGENTS.md for other agents, import it from CLAUDE.md so both runtimes share the same instructions:

@AGENTS.md

## Claude Code

(Claude-Code-specific instructions go here.)

For path-scoped rules and larger-project organization, see .claude/rules/ (rules can be scoped to specific files via paths frontmatter and load on demand).

Personal skills directory

User-level skills live at `~/.claude/skills/`. Each skill is a subdirectory containing a SKILL.md (with name and description frontmatter) plus any supporting files. Claude Code does not currently recognize the cross-runtime ~/.agents/skills/ path that Codex, Copilot CLI, and Gemini CLI read; if you're relying on cross-runtime support in the future, verify against the official skills docs.

Codex Tool Mapping

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

Instructions file

When a skill mentions "your instructions file", on Codex this is `AGENTS.md` at the project root. Codex also reads ~/.codex/AGENTS.md for global context, and an AGENTS.override.md (in the project tree or ~/.codex/) takes precedence when present. Codex walks from the project root down to the current working directory, concatenating AGENTS.md files it finds along the way, up to project_doc_max_bytes (32 KiB by default).

Personal skills directory

User-level skills live at `$CODEX_HOME/skills/` (default ~/.codex/skills/). Codex also reads the cross-runtime path `~/.agents/skills/` (shared with Copilot CLI and Gemini CLI). When both directories exist at the same scope, Codex loads them both as separate skill catalogs — Codex's docs don't currently document a precedence between them. Each skill is a subdirectory containing a SKILL.md (with name and description frontmatter).

Subagent dispatch requires multi-agent support

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

[features]
multi_agent = true

This enables spawn_agent, wait_agent, and close_agent for skills like dispatching-parallel-agents and subagent-driven-development.

Legacy note: Codex builds before rust-v0.115.0 exposed spawned-agent waiting as wait. Current Codex uses wait_agent for spawned agents. The wait name now belongs to code-mode exec/wait, which resumes a yielded exec cell by cell_id; it is not the spawned-agent result tool.

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.

Copilot CLI Tool Mapping

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

Instructions file

When a skill mentions "your instructions file", on Copilot CLI this is `AGENTS.md` at the repository root. If both AGENTS.md and .github/copilot-instructions.md are present, Copilot reads both.

Personal skills directory

User-level skills live at `~/.copilot/skills/`. Copilot CLI also recognizes the cross-runtime alias `~/.agents/skills/`, which is shared with Codex and Gemini CLI. Each skill is a subdirectory containing a SKILL.md (with name and description frontmatter).

Async shell sessions

Copilot CLI supports persistent async shell sessions:

Additional Copilot CLI tools

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.

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:

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:

Pi Tool Mapping

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

Skills

Pi discovers skills from configured skill directories and installed Pi packages. A Superpowers Pi package should expose skills/ through its pi.skills manifest entry. Pi does not expose Claude Code's Skill tool, but the agent should still follow the Superpowers rule: when a skill applies, load and follow it before responding.

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.