using-superpowers

Visão geral

O que a skill using-superpowers faz

A skill using-superpowers é um bootstrapper de conversas para agentes de IA. Ela define como um agente deve:

• Decidir quando invocar skills (e tornar isso obrigatório quando for relevante)
• Priorizar instruções entre pedidos do usuário, skills superpowers e o comportamento padrão do sistema
• Acessar e ativar skills corretamente em diferentes plataformas como Claude Code e Gemini CLI
• Traduzir nomes padrão de ferramentas "superpowers" para equivalentes específicos de cada plataforma

Esta skill deve ser usada no início de qualquer nova conversa ou tarefa. Ela estabelece um contrato compartilhado: se houver qualquer chance, mesmo pequena, de uma skill se aplicar, o agente deve invocá-la antes de responder, inclusive antes de fazer perguntas de esclarecimento.

Para quem a using-superpowers é indicada

Use a skill using-superpowers se você é:

• Um desenvolvedor configurando Claude Code, Gemini CLI ou ambientes semelhantes
• Responsável por um workspace com múltiplas skills e múltiplos agentes e quer um comportamento consistente
• Usuário do repositório obra/superpowers como uma biblioteca padrão de skills
• Responsável por fluxos de trabalho internos em que agentes precisam seguir procedimentos documentados e usar as ferramentas corretas

Ela é especialmente útil em projetos maiores, onde deixar de usar uma skill relevante (como uma skill de code review ou de planejamento) pode levar a resultados inconsistentes ou à falta de checagens de segurança.

Problemas que esta skill resolve

A skill using-superpowers trata de vários problemas comuns em fluxos de trabalho baseados em agentes:

• Agentes respondendo “no instinto” em vez de verificar skills disponíveis
• Dúvida sobre se instruções do usuário ou skills são a fonte principal de verdade
• Uso incorreto de ferramentas (por exemplo, ler arquivos de skill diretamente em vez de usar a ferramenta Skill)
• Diferenças entre plataformas como Claude Code, Gemini CLI e outros ambientes

Ao instalar e ativar using-superpowers, você reduz essas inconsistências e deixa claro como as skills devem ser descobertas e usadas.

Quando a using-superpowers é (ou não é) adequada

Boa escolha quando:

• Você depende de múltiplas skills que precisam ser seguidas de forma consistente
• Você quer que os agentes sempre verifiquem skills relevantes antes de continuar
• Você atua em múltiplas plataformas e precisa de um mapeamento entre nomes de ferramentas
• Você está construindo ou organizando uma biblioteca de skills no estilo superpowers

Não é uma boa escolha quando:

• Você é um subagente de uso único, disparado para uma tarefa bem estreita (a skill afirma explicitamente que subagentes devem ignorá-la)
• Você tem apenas uma configuração mínima, sem skills adicionais ou integrações de ferramentas
• Você quer um comportamento totalmente livre e exploratório, sem regras rígidas sobre quando invocar skills

---

Como usar

1. Instale a skill using-superpowers

Instale using-superpowers a partir do repositório obra/superpowers usando o Skills CLI:

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

Isso traz a definição da skill using-superpowers e seus materiais de referência para o seu ambiente de skills.

Após a instalação, você deve ver pelo menos estes arquivos para esta skill:

• SKILL.md — comportamento principal e prioridade de instruções
• references/codex-tools.md — mapeamento de ferramentas para ambientes ao estilo Codex
• references/gemini-tools.md — mapeamento de ferramentas para Gemini CLI

2. Entenda a regra de subagentes

A skill inclui uma proteção para subagentes:

• Se um agente for disparado como subagente para executar uma tarefa específica, ele deve pular esta skill.
• Isso mantém subagentes focados em sua tarefa e evita reinicializar o comportamento global de skills.

Como designer de fluxo de trabalho, você deve:

• Garantir que seu agente principal invoque using-superpowers no início de uma conversa
• Configurar subagentes para que eles não executem novamente esta skill quando forem criados para um trabalho dedicado

3. Siga o modelo de prioridade de instruções

using-superpowers define uma hierarquia clara de instruções:

1. Instruções do usuário — prioridade máxima
   • Prompts diretos do usuário
   • Arquivos específicos do projeto como CLAUDE.md, GEMINI.md, AGENTS.md
2. Skills superpowers — incluindo using-superpowers e outras skills da biblioteca
3. Prompt padrão do sistema / defaults do modelo — prioridade mais baixa

Na prática, isso significa:

• Se CLAUDE.md ou GEMINI.md entrar em conflito com uma skill, o arquivo do usuário prevalece.
• Skills superpowers podem substituir o comportamento padrão do modelo apenas quando não contradizem instruções do usuário.
• O prompt padrão do sistema preenche as lacunas quando nem instruções do usuário nem skills se aplicam.

Ao configurar seu ambiente, certifique-se de que todas essas fontes estejam visíveis e de que seu agente principal conheça essa ordem.

4. Imponha a invocação obrigatória de skills

Uma regra central de using-superpowers é que a invocação de skills é obrigatória quando relevante:

• Se houver nem que seja 1% de chance de uma skill se aplicar à tarefa atual, o agente deve invocá-la.
• Os agentes não devem responder nem fazer perguntas de esclarecimento antes de invocar a skill relevante quando ela possa se aplicar.

Essa regra foi criada para:

• Evitar que agentes “pulem” skills que carregam lógica importante de segurança ou de fluxo de trabalho
• Incentivar uma abordagem skills-first, em que o agente procura e usa a skill correta antes de improvisar

Como desenvolvedor, você pode:

• Tratar isso como parte da sua política organizacional para agentes
• Explicar aos usuários que, nas primeiras etapas da conversa, o agente pode invocar skills antes de responder

5. Use o método correto de acesso a skills em cada plataforma

A skill using-superpowers define como acessar skills em diferentes plataformas.

Claude Code

• Use a ferramenta Skill para invocar skills.
• Quando uma skill é invocada, seu conteúdo é carregado e apresentado ao agente — o agente deve segui-la diretamente.
• O agente não deve usar a ferramenta Read para abrir arquivos de skill; ele deve depender da ferramenta Skill para isso.

Gemini CLI

• As skills são ativadas pela ferramenta activate_skill.
• O Gemini carrega metadados de skills no início da sessão e ativa o conteúdo completo sob demanda.
• Quando uma skill é ativada, o agente deve seguir as instruções fornecidas por essa skill.

Outros ambientes

Para ambientes além de Claude Code e Gemini CLI:

• Consulte a documentação da sua plataforma sobre como ela lida com ativação de skills ou fluxos baseados em ferramentas.
• Use as referências fornecidas neste repositório como guia para mapear os nomes genéricos de ferramentas "superpowers" para os equivalentes da sua plataforma.

6. Faça o mapeamento de ferramentas para ambientes ao estilo Codex

Se você estiver usando um Codex CLI ou ambiente semelhante, leia:

• references/codex-tools.md

Conceitos-chave dessa referência:

• As skills usam nomes de ferramentas do Claude Code por padrão.
• O arquivo traz uma tabela de mapeamento entre ferramentas superpowers e equivalentes Codex, incluindo:
  • Task → spawn_agent
  • Múltiplas chamadas Task → múltiplas chamadas spawn_agent
  • Resultado de Task → wait
  • Conclusão de Task → close_agent
  • TodoWrite → update_plan
  • Skill → tratamento nativo de skills
  • Read / Write / Edit / Bash → ferramentas correspondentes de arquivos e shell no Codex

Ele também documenta:

• Como habilitar suporte multi-agente no Codex adicionando em ~/.codex/config.toml:

[features]
multi_agent = true

• Como lidar com disparo de agentes nomeados quando o Codex não tem um registro de agentes nomeados, incluindo ler um arquivo de prompt (como agents/code-reviewer.md), preencher placeholders e criar um agente worker com esse prompt.

7. Faça o mapeamento de ferramentas para Gemini CLI

Para uso com Gemini CLI, leia:

• references/gemini-tools.md

Essa referência explica como as ferramentas superpowers padrão se mapeiam para ferramentas do Gemini CLI, por exemplo:

• 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

Ela também observa que:

• O Gemini CLI não oferece suporte a subagentes — não há equivalente para a ferramenta Task.
• Skills que dependem de subagentes (como subagent-driven-development ou dispatching-parallel-agents) passam a usar execução em sessão única por meio de outras skills de planejamento (como executing-plans).
• O Gemini CLI inclui ferramentas adicionais sem equivalente direto no Claude Code, como list_directory, save_memory, ask_user, tracker_create_task e enter_plan_mode / exit_plan_mode.

8. Ordem de leitura recomendada

Para obter o máximo da using-superpowers em um novo workspace:

1. Comece por SKILL.md
   • Entenda a prioridade de instruções e as regras de invocação obrigatória de skills.
2. Abra references/codex-tools.md (se você usa Codex ou ambiente similar)
   • Configure suporte multi-agente e o mapeamento de ferramentas.
3. Abra references/gemini-tools.md (se você usa Gemini CLI)
   • Entenda o mapeamento de ferramentas e a ausência de suporte a subagentes.

Depois disso, você pode adaptar esses padrões às suas próprias ferramentas e arquivos de configuração.

---

Perguntas frequentes (FAQ)

Como instalo a skill using-superpowers?

Use o Skills CLI para adicioná-la a partir do repositório obra/superpowers:

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

Depois da instalação, abra SKILL.md para ver as regras centrais e a pasta references/ para os mapeamentos de ferramentas específicos de cada plataforma.

Quando um agente deve executar a using-superpowers?

A skill using-superpowers foi criada para ser executada no início de uma conversa ou tarefa pelo seu agente principal. Ela deve ser usada quando um agente estiver prestes a:

• Começar a trabalhar em um projeto que usa skills superpowers
• Decidir quais skills usar para uma nova solicitação
• Operar em um ambiente de desenvolvimento com múltiplas ferramentas e múltiplas plataformas

Subagentes disparados para tarefas estreitas devem pular esta skill e seguir apenas os prompts ou instruções que receberam.

A using-superpowers substitui instruções do usuário?

Não. A skill declara explicitamente que instruções do usuário sempre têm prioridade. A ordem de prioridade é:

1. Instruções do usuário (incluindo CLAUDE.md, GEMINI.md, AGENTS.md e prompts diretos)
2. Skills superpowers como using-superpowers
3. Comportamento padrão do prompt do sistema

Se houver conflito entre uma instrução do usuário e uma skill, o agente deve seguir a instrução do usuário.

O que significa “invocação obrigatória de skills” na prática?

Invocação obrigatória de skills significa:

• Se houver qualquer chance realista de uma skill se aplicar à tarefa atual, o agente deve invocá-la.
• O agente não deve responder nem fazer perguntas de esclarecimento primeiro quando possa existir uma skill relevante.

Isso ajuda a garantir que:

• Skills de segurança e de fluxo de trabalho sejam aplicadas de forma consistente
• Agentes se apoiem em procedimentos testados em vez de improvisar

Como a using-superpowers afeta o Claude Code?

No Claude Code:

• Os agentes devem usar a ferramenta Skill para carregar e seguir skills, inclusive using-superpowers.
• Eles não devem usar a ferramenta Read para abrir arquivos de skill diretamente.
• Uma vez que using-superpowers esteja ativa, o agente segue as diretrizes dela sobre prioridade de instruções e invocação de skills.

Você pode combinar isso com outras skills do mesmo repositório para criar um fluxo de desenvolvimento robusto, guiado por skills.

Como a using-superpowers funciona com o Gemini CLI?

Com o Gemini CLI:

• As skills são ativadas usando a ferramenta activate_skill.
• using-superpowers explica que o Gemini carrega metadados de skills no início da sessão e que o conteúdo completo é ativado quando solicitado.
• Os nomes de ferramentas mencionados nas skills superpowers são mapeados para ferramentas do Gemini CLI em references/gemini-tools.md.

Lembre-se de que o Gemini CLI não oferece suporte a subagentes; skills que dependem de disparo de subagentes passam automaticamente a usar padrões de execução em sessão única.

Posso usar a using-superpowers em outras plataformas de agentes?

Sim, desde que sua plataforma suporte o conceito de skills ou ferramentas:

• Use SKILL.md como referência principal para o comportamento e a prioridade de instruções.
• Revise references/codex-tools.md e references/gemini-tools.md como exemplos de como mapear nomes de ferramentas superpowers para a sua plataforma.
• Implemente uma camada de mapeamento semelhante para alinhar as ferramentas da sua plataforma às expectativas da skill.

Talvez você precise adaptar ou estender os mapeamentos dependendo dos recursos da sua plataforma.

Quais arquivos devo ler primeiro depois de instalar a skill?

Para uma configuração rápida e prática:

1. SKILL.md — comportamento central, prioridade de instruções e regra de invocação obrigatória de skills.
2. references/codex-tools.md — se você usa Codex ou um ambiente semelhante ao Codex.
3. references/gemini-tools.md — se você usa Gemini CLI.

A partir daí, você pode explorar outras skills no repositório obra/superpowers para montar um fluxo de trabalho mais completo.

A using-superpowers é suficiente sozinha?

using-superpowers fornece a base de como as skills devem ser descobertas e aplicadas, mas ela é muito mais útil quando combinada com outras skills do mesmo ecossistema (para planejamento, code review, testes etc.).

Use-a como a primeira camada da configuração do seu agente e, em seguida, adicione skills específicas do seu domínio conforme as necessidades do projeto.