using-superpowers

Overview

What the using-superpowers skill does

The using-superpowers skill is a conversation bootstrapper for AI agents. It defines how an agent should:

• Decide when to invoke skills (and make that non‑optional when relevant)
• Prioritize instructions between user prompts, superpowers skills, and default system behavior
• Access and activate skills correctly on different platforms like Claude Code and Gemini CLI
• Translate standard "superpowers" tool names to platform‑specific equivalents

This skill is meant to be used at the start of any new conversation or task. It establishes a shared contract: if there is even a small chance a skill applies, the agent must invoke it before answering, including before asking clarifying questions.

Who using-superpowers is for

Use the using-superpowers skill if you are:

• A developer configuring Claude Code, Gemini CLI, or similar environments
• Maintaining a multi-skill, multi-agent workspace and want consistent behavior
• Using the obra/superpowers repository as a standard library of skills
• Building internal workflows where agents must follow documented procedures and use the right tools

It is especially useful in larger projects where missing a relevant skill (like a code review or planning skill) can lead to inconsistent results or skipped safety checks.

Problems this skill solves

The using-superpowers skill addresses several common issues in agent-based workflows:

• Agents answering from intuition instead of checking available skills
• Confusion over whether user instructions or skills are authoritative
• Misuse of tooling (e.g., reading skill files directly instead of using the Skill tool)
• Platform differences between Claude Code, Gemini CLI, and other environments

By installing and activating using-superpowers, you reduce these inconsistencies and make it clear how skills should be discovered and used.

When using-superpowers is and isn’t a good fit

Good fit when:

• You rely on multiple skills that must be followed in a consistent way
• You want agents to always check for relevant skills before proceeding
• You operate across multiple platforms and need a mapping between tool names
• You are building or curating a superpowers-style skill library

Not a good fit when:

• You are a single-use subagent dispatched for a narrowly scoped task (the skill explicitly says subagents should skip it)
• You only have a minimal setup without additional skills or tool integrations
• You want fully free-form, exploratory behavior without strict rules about when to invoke skills

---

How to Use

1. Install the using-superpowers skill

Install using-superpowers from the obra/superpowers repository using the Skills CLI:

npx skills add https://github.com/obra/superpowers --skill using-superpowers

This pulls the using-superpowers skill definition and its reference material into your skills environment.

After installation, you should see at least these files for this skill:

• SKILL.md — primary behavior and instruction priority
• references/codex-tools.md — tool mapping for Codex-style environments
• references/gemini-tools.md — tool mapping for Gemini CLI

2. Understand the subagent rule

The skill includes a subagent guard:

• If an agent is dispatched as a subagent to perform a specific task, it should skip this skill.
• This keeps subagents focused on their task and avoids re-initializing the global skill behavior.

As a workflow designer, you should:

• Ensure your primary agent invokes using-superpowers at the start of a conversation
• Configure subagents so they do not re-run this skill when spawned for a dedicated job

3. Follow the instruction priority model

using-superpowers defines a clear hierarchy for instructions:

1. User instructions — top priority
   • Direct user prompts
   • Project-specific files like CLAUDE.md, GEMINI.md, AGENTS.md
2. Superpowers skills — including using-superpowers and other skills from the library
3. Default system prompt / model defaults — lowest priority

Practically, this means:

• If CLAUDE.md or GEMINI.md conflicts with a skill, the user’s file wins.
• Superpowers skills can override default model behavior only when they don’t contradict user instructions.
• The default system prompt fills in the gaps when neither user instructions nor skills apply.

When configuring your environment, make sure these sources are all visible and that your primary agent is aware of this ordering.

4. Enforce mandatory skill invocation

A core rule of using-superpowers is that skill invocation is mandatory when relevant:

• If there is even a 1% chance that a skill applies to the current task, the agent must invoke it.
• Agents should not answer or ask clarifying questions before invoking the relevant skill when it might apply.

This rule is designed to:

• Prevent agents from “skipping” skills that carry important safety or workflow logic
• Encourage a skills-first approach, where the agent searches and uses the right skill before improvising

As a developer, you can:

• Treat this as part of your organizational agent policy
• Explain to users that early conversation steps may involve the agent invoking skills before responding

5. Use the correct skill access method per platform

The using-superpowers skill defines how to access skills on different platforms.

Claude Code

• Use the Skill tool to invoke skills.
• When a skill is invoked, its content is loaded and presented to the agent — the agent should follow it directly.
• The agent should not use the Read tool to open skill files; it should rely on the Skill tool for that.

Gemini CLI

• Skills activate through the activate_skill tool.
• Gemini loads skill metadata at session start and activates the full content on demand.
• When a skill is activated, the agent should follow the instructions provided by that skill.

Other environments

For environments beyond Claude Code and Gemini CLI:

• Consult your platform’s documentation for how it handles skill activation or tool-based workflows.
• Use the references provided in this repository as a guide for mapping the generic "superpowers" tool names to your platform’s equivalents.

6. Map tools to Codex-style environments

If you are using a Codex CLI or similar environment, read:

• references/codex-tools.md

Key concepts from that reference:

• Skills use Claude Code tool names by default.
• The file provides a mapping table between superpowers tools and Codex equivalents, including:
  • Task → spawn_agent
  • Multiple Task calls → multiple spawn_agent calls
  • Task result → wait
  • Task completion → close_agent
  • TodoWrite → update_plan
  • Skill → native skills handling
  • Read / Write / Edit / Bash → corresponding Codex file and shell tools

It also documents:

• How to enable multi-agent support in Codex by adding to ~/.codex/config.toml:

[features]
multi_agent = true

• How to handle named agent dispatch when Codex does not have a named agent registry, including reading a prompt file (like agents/code-reviewer.md), filling placeholders, and spawning a worker agent with that prompt.

7. Map tools to Gemini CLI

For Gemini CLI usage, read:

• references/gemini-tools.md

This reference explains how standard superpowers tools map to Gemini CLI tools, for example:

• Read → read_file
• Write → write_file
• Edit → replace
• Bash → run_shell_command
• Grep → grep_search
• Glob → glob
• TodoWrite → write_todos
• Skill → activate_skill
• WebSearch → google_web_search
• WebFetch → web_fetch

It also notes:

• Gemini CLI does not support subagents — there is no equivalent to the Task tool.
• Skills that depend on subagents (like subagent-driven-development or dispatching-parallel-agents) fall back to single-session execution via other planning skills (such as executing-plans).
• Gemini CLI includes additional tools with no direct Claude Code equivalent, like list_directory, save_memory, ask_user, tracker_create_task, and enter_plan_mode / exit_plan_mode.

8. Recommended reading order

To get the most value from using-superpowers in a new workspace:

1. Start with SKILL.md
   • Understand the instruction priority and mandatory skill invocation rules.
2. Open references/codex-tools.md (if you use Codex or a similar environment)
   • Configure multi-agent support and tool mappings.
3. Open references/gemini-tools.md (if you use Gemini CLI)
   • Learn the tool mapping and the lack of subagent support.

You can then adapt these patterns to your own tools and configuration files.

---

FAQ

How do I install the using-superpowers skill?

Use the Skills CLI to add it from the obra/superpowers repository:

npx skills add https://github.com/obra/superpowers --skill using-superpowers

Once installed, open SKILL.md for the core rules, and the references/ folder for platform-specific tool mappings.

When should an agent run using-superpowers?

The using-superpowers skill is designed to run at the start of a conversation or task for your primary agent. It should be used when an agent is about to:

• Begin working in a project that has superpowers skills
• Decide which skills to use for a new request
• Operate in a multi-tool, multi-platform development environment

Subagents dispatched for narrow tasks should skip this skill and instead follow the prompts or instructions passed to them.

Does using-superpowers override user instructions?

No. The skill explicitly states that user instructions always take precedence. The instruction priority is:

1. User instructions (including CLAUDE.md, GEMINI.md, AGENTS.md, and direct user prompts)
2. Superpowers skills like using-superpowers
3. Default system prompt behavior

If there is a conflict between a user instruction and a skill, the agent must follow the user’s instruction.

What does “mandatory skill invocation” mean in practice?

Mandatory skill invocation means:

• If there is any realistic chance that a skill applies to the current task, the agent must invoke it.
• The agent should not answer or ask clarifying questions first when a relevant skill might exist.

This helps ensure that:

• Safety and workflow skills are consistently applied
• Agents rely on tested procedures instead of improvising

How does using-superpowers affect Claude Code?

In Claude Code:

• Agents should use the Skill tool to load and follow skills, including using-superpowers.
• They should not use the Read tool to open skill files directly.
• Once using-superpowers is active, the agent follows its guidelines for instruction priority and skill invocation.

You can combine this with additional skills from the same repository to create a robust, skill-driven development workflow.

How does using-superpowers work with Gemini CLI?

With Gemini CLI:

• Skills are activated using the activate_skill tool.
• using-superpowers explains that Gemini loads skill metadata at session start and that full content is activated when requested.
• Tool names referenced in superpowers skills are mapped to Gemini CLI tools in references/gemini-tools.md.

Keep in mind that Gemini CLI does not support subagents; skills that depend on subagent dispatch automatically fall back to single-session execution patterns.

Can I use using-superpowers in other agent platforms?

Yes, as long as your platform supports the concept of skills or tools:

• Use SKILL.md as the source of truth for behavior and instruction priority.
• Review references/codex-tools.md and references/gemini-tools.md as examples of how to map superpowers tool names to your platform.
• Implement a similar mapping layer so your platform’s tools align with the skill expectations.

You may need to adapt or extend the mappings depending on your platform’s capabilities.

What files should I read first after installing the skill?

For a quick, practical setup:

1. SKILL.md — core behavior, instruction priority, and mandatory skill invocation rule.
2. references/codex-tools.md — if you use Codex or a Codex-like environment.
3. references/gemini-tools.md — if you use Gemini CLI.

From there, you can explore other skills in the obra/superpowers repository to build a more complete workflow.

Is using-superpowers enough on its own?

using-superpowers provides the foundation for how skills should be discovered and applied, but it is most powerful when combined with other skills from the same ecosystem (for planning, code review, testing, etc.).

Use it as the first layer of your agent configuration, then add domain-specific skills on top based on your project’s needs.