using-superpowers

Overview of using-superpowers skill

What the using-superpowers skill actually does

The using-superpowers skill is a session-start control skill from the obra/superpowers repo. Its main job is not to solve a domain task directly, but to make sure the agent checks for relevant skills before replying, even before asking clarifying questions. In practice, it turns “just answer from the base model” into “look for the right skill first, then proceed.”

Best fit for using-superpowers

This skill is best for users who want a skills-first workflow in Claude Code, Gemini CLI, or another compatible environment with skill activation. It is especially useful if you install multiple skills and want more reliable discovery, better instruction routing, and less chance that the agent forgets a specialized workflow.

Real job-to-be-done

The real use case is governance and consistency: make the agent treat skill lookup as mandatory when there is any plausible fit. If your main problem is “the assistant ignores available skills and improvises,” using-superpowers addresses that directly.

Why users install it

Users typically care about three things before adopting using-superpowers:

1. Will it reduce missed skill usage?
2. Will it conflict with my own repo instructions?
3. Will it work in my current tool environment?

On those points, the skill is strong: it clearly states that user instructions remain highest priority, and it includes platform mapping references for Claude-style tools, Codex-style tools, and Gemini CLI.

Key differentiators from a generic prompt

Unlike a normal “please use tools when relevant” prompt, using-superpowers is explicit and strict. It defines a hard rule: if there is even a small chance a skill applies, the agent must invoke it. It also documents instruction priority and environment-specific activation paths, which makes it more operational than a vague reminder.

Important limitation to know first

using-superpowers is only valuable if your environment actually supports skills or an equivalent activation mechanism. It also includes a subagent stop condition, so it is aimed at the main session, not every delegated task. If you do not use a skill-enabled workflow, this is more policy than functionality.

How to Use using-superpowers skill

Install context for using-superpowers

The repository excerpt does not publish an in-skill install command, so install it through your skill manager or platform-specific skill setup for the obra/superpowers repository and select the using-superpowers skill from skills/using-superpowers.

If your tooling supports repo-based install syntax, verify the exact command in your environment's docs before copying examples from third-party pages. The important part is that the skill path is using-superpowers within https://github.com/obra/superpowers.

Where using-superpowers belongs in your workflow

Use using-superpowers at the start of a conversation or session, not midway through a deeply committed workflow. Its purpose is to set behavior before the agent starts choosing tools, asking questions, or planning work.

This is the right mental model:

• First activate using-superpowers
• Then state your task
• Then let the agent discover and invoke any more specific skill that fits

How the skill is invoked in practice

The repository states the intended activation path clearly:

• In Claude Code, use the Skill tool
• In Gemini CLI, use activate_skill
• In Codex-like environments, follow the skill instructions natively and use the reference mapping for tool equivalents

Do not read the skill file as plain text when your platform supports skill activation; the skill explicitly says to invoke it through the proper skill mechanism.

What input using-superpowers needs

The skill itself needs very little input. What matters is the task you provide immediately after activation. A weak input is broad and underspecified:

• “Help with my codebase”

A stronger input gives enough shape for skill discovery:

• “I need to review a Python PR for correctness, find risky changes, and suggest follow-up tests.”
• “I want to implement a feature in this repo using the project’s conventions and existing agent workflow.”
• “Help me decide which superpowers skill applies to debugging a flaky CLI integration test.”

The more concrete the goal, artifact, and environment, the better the downstream skill selection.

Turn a rough goal into a better using-superpowers prompt

A practical using-superpowers usage pattern is:

1. State the task
2. Name the repo or files involved
3. Mention constraints
4. Ask the agent to discover and use matching skills before proceeding

Example:

Activate using-superpowers. I need to refactor src/auth/session.ts, preserve public behavior, avoid new dependencies, and follow this repo’s conventions. Check for any applicable skills before proposing changes.

Why this works: it gives the skill discovery step enough context to choose something more specific than a generic coding response.

Repository files to read first

If you are evaluating using-superpowers for Skill Discovery, read these files first:

1. skills/using-superpowers/SKILL.md
2. skills/using-superpowers/references/codex-tools.md
3. skills/using-superpowers/references/gemini-tools.md

This reading order answers the main install decision quickly: core rule, instruction priority, then platform compatibility.

What matters most in SKILL.md

Focus on four parts of SKILL.md:

• The session-start requirement
• The “1% chance a skill applies” rule
• Instruction priority
• Platform access guidance

Those are the parts that materially affect agent behavior. They tell you whether using-superpowers will be helpful, overbearing, or compatible with your setup.

Platform adaptation guidance

The references folder is more useful than it looks. It translates Claude Code-centric tool names into other environments:

• references/codex-tools.md explains mappings like Task to spawn_agent, TodoWrite to update_plan, and the lack of named agent registry
• references/gemini-tools.md explains mappings like Skill to activate_skill and calls out that Gemini CLI has no subagent support

If you are not in Claude Code, these files are the difference between “interesting repo” and “usable workflow.”

Suggested workflow after activation

A practical using-superpowers guide looks like this:

1. Activate using-superpowers
2. Give a concrete task with files, constraints, and success criteria
3. Let the agent identify an applicable specialized skill
4. Follow that specialized skill for execution
5. Re-check user-level instructions such as AGENTS.md, CLAUDE.md, or GEMINI.md if there is any conflict

This workflow keeps using-superpowers in its proper role: gatekeeper, not end-task solver.

Tradeoffs and constraints before adoption

The main tradeoff is strictness. using-superpowers improves consistency, but it can make the workflow feel heavier if you only use one or two skills or prefer loose conversational exploration. It is also opinionated: it pushes skill invocation before even clarifying questions, which some users may find too rigid.

The main constraint is ecosystem maturity. If your environment lacks robust skill support, the policy may be clearer than the execution path.

using-superpowers skill FAQ

Is using-superpowers worth installing if I only use a few skills?

Usually yes, if those few skills matter and you want them used reliably. If you rarely forget to invoke skills manually, the benefit is smaller. The strongest case is when missed skill discovery causes lower-quality output or inconsistent workflows.

Is using-superpowers beginner-friendly?

Yes, with one caveat: beginners benefit from the strong default of “check for a skill first,” but they still need to understand how their platform activates skills. The reference files help, especially for Gemini CLI and Codex-style environments.

Does using-superpowers override my project instructions?

No. The skill explicitly says user instructions take precedence over superpowers skills, and those skills override only the default system behavior. If your repo-level instruction says not to use a given workflow, that higher-priority instruction wins.

When should I not use using-superpowers?

Skip it if:

• Your environment does not support skills well
• You are intentionally doing a quick one-off interaction with no skill ecosystem
• You are running as a subagent on a narrow delegated task, since the skill includes a subagent stop instruction

How is using-superpowers different from just telling the model to use skills?

The difference is enforcement and clarity. A normal prompt is a suggestion; using-superpowers is a structured operating rule with explicit priority handling and platform notes. That makes it more dependable in repeated use.

Does using-superpowers work for Skill Discovery specifically?

Yes. In fact, that is its core value. using-superpowers for Skill Discovery is strongest when you have a growing library of skills and want the agent to treat discovery as mandatory rather than optional.

How to Improve using-superpowers skill

Give better task framing after activating using-superpowers

The biggest quality lever is not the activation itself, but the first task message after it. Include:

• exact objective
• relevant files or directories
• constraints
• preferred workflow
• definition of done

This produces better skill matching than broad requests.

Common failure mode: vague goals produce weak skill selection

If you say “help me with this repo,” the agent may still discover a skill, but it has little basis for choosing the best one. Replace vague prompts with task-shaped requests such as:

• “Find the right skill for reviewing a risky migration diff”
• “Use any relevant superpowers skill before proposing a plan to debug CI failures”
• “Determine whether this task fits a planning, implementation, or review skill”

Common failure mode: platform mismatch

A frequent adoption blocker is reading Claude-style tool names literally in another environment. Fix this by checking the reference file that matches your platform before judging the skill. For Codex, start with references/codex-tools.md; for Gemini CLI, start with references/gemini-tools.md.

Improve using-superpowers with repo-level instructions

using-superpowers works better when your repo already has clear high-priority instructions in AGENTS.md, CLAUDE.md, or GEMINI.md. The skill respects those files, so good local guidance reduces conflicts and improves how discovered skills are applied.

Use using-superpowers as a routing layer, not the final method

A common mistake is expecting the using-superpowers skill to contain all execution details. It is better viewed as a router into the rest of the superpowers ecosystem. For better results, pair it with a specific downstream skill instead of stopping at activation.

Iterate after the first response

If the first response does not clearly identify or invoke a relevant skill, tighten your prompt instead of abandoning the workflow. Add:

• the exact artifact to operate on
• the type of work needed
• any important limitation
• a direct instruction to check for applicable skills before proceeding

That usually improves both skill discovery and execution quality.