Superpowers wiki: o que a documentação explica sobre cada skill do framework?

Fala aí, beleza? Você abre o repositório do Superpowers, vê uma pasta cheia de arquivo markdown e não faz ideia de por onde começar a ler

Acontece com todo mundo

O Superpowers se descreve como um framework de skills agênticas e metodologia de desenvolvimento de software, mantido por Jesse Vincent (o usuário obra no GitHub) junto com a equipe da Prime Radiant

E a documentação em formato wiki é o caminho mais rápido pra entender o que cada skill faz ANTES de instalar qualquer coisa na sua máquina

Bora destrinchar isso? 🙂

Onde fica a documentação do Superpowers e quem escreveu cada parte

Aqui mora a primeira confusão: não existe uma documentação só, existem fontes diferentes com autorias diferentes

Se liga na separação:

• O repositório principal: github.com/obra/superpowers, onde cada skill é uma pasta com um arquivo SKILL.md em markdown, com frontmatter YAML e seções de orientação estruturada (o caminho é skills/<nome-da-skill>/SKILL.md)
• A pasta docs/: traz README.kimi.md, README.opencode.md, porting-to-a-new-harness.md e testing.md, ou seja, documentação por harness e um guia de portabilidade pra novos ambientes
• O RELEASE-NOTES.md e a aba de Releases: é onde tu confere o que mudou nas skills ao longo do tempo

E a ressalva mais importante de todas

Formação Recomendada

Formação Vibe Coding

Do Prompt ao Produto: Crie Software Real com IA

• 474 aulas
• 20 projetos
• 39h 27min

Conhecer formação

A wiki mais completa sobre cada skill não está no GitHub: está no DeepWiki, com páginas separadas de fluxos de desenvolvimento, referência de skills e criação de skills

Que serviço é esse? O DeepWiki é da Cognition AI (a empresa do agente Devin), foi lançado em 25 de abril de 2025 e gera documentação por IA pra repositórios públicos: tu troca github.com por deepwiki.com na URL e pronto

Ou seja: é documentação gerada por IA a partir do código, não texto escrito pelo autor do projeto

Ótima pra ter o mapa geral na cabeça, mas o SKILL.md continua sendo a palavra final

Uma dica de quem gosta de estudar antes de sair instalando: dá pra jogar essas páginas num caderno e estudar a documentação com o NotebookLM antes de tomar decisão

Tome cuidado com o repositório errado:

Esse é o tropeço clássico de quem procura a wiki e cai em outro lugar

O marketplace vive em um repositório SEPARADO, com sufixo no nome: obra/superpowers-marketplace

E ainda tem um terceiro, o obra/superpowers-skills, descrito como skills editáveis pela comunidade, que o plugin clona automaticamente pra pasta local ~/.config/superpowers/skills/

Três repositórios, três papéis diferentes

Quem não sabe disso passa meia hora procurando skill em repositório que não tem a skill que ele quer, haha

A sequência que a documentação propõe, fase a fase

O Superpowers não é um saco de skills soltas pra tu chamar na sorte

A documentação descreve um pipeline principal, encadeado, com portões de aprovação humana no meio

1. brainstorming: roda ANTES de escrever código, explora intenção e requisitos por diálogo de uma pergunta por vez, apresenta o design em blocos pra tu validar e salva um documento de design no fim

O erro comum deste passo é chegar pedindo implementação: se tu manda "cria o app" na primeira mensagem, tu está tentando furar justamente o portão que a skill existe pra impor

2. writing-plans: é a fase de arquitetura, indicada logo depois do design aprovado, e o plano gerado é gravado em docs/superpowers/plans/

Depois de escrever o plano, o agente oferece a escolha de execução

O erro comum aqui é aprovar o plano no automático, sem ler: o portão de aprovação do plano só tem valor se tu de fato revisar o que está escrito ali

3. subagent-driven-development: a execução do que foi planejado

O erro comum é esperar que essa fase conserte um design vago que passou batido nas duas anteriores, e não é assim que funciona

Repara na espinha do negócio: são dois portões obrigatórios de aprovação humana, o do design (imposto pela skill brainstorming) e o do plano (imposto pela writing-plans)

Sem confirmação explícita, o avanço trava

É opinativo? MUITO

Mas é exatamente esse o ponto do framework

Referência das principais skills: o que cada uma faz e quando entra

A página de referência de skills do DeepWiki é a que mais resolve dúvida de quem está avaliando o framework

Montei um resumo varrível do que a documentação atribui a cada uma:

Dois detalhes da using-git-worktrees que valem o zoom: ela verifica se o diretório de worktree está no .gitignore e, se existirem .worktrees/ e worktrees/, a prioridade é do .worktrees/

Já a systematic-debugging é bem específica no protocolo, e dá pra contar as quatro fases na ordem

Primeira: investigar a causa antes de encostar em qualquer correção

Segunda: criar um teste de reprodução que falha (usando test-driven-development)

Terceira: aplicar UMA única correção na causa raiz, sem refatoração extra de brinde

Quarta: verificar que o teste passa sem quebrar os outros

É o oposto do chute-e-testa que a gente faz às 2 da manhã 😛

Para que serve cada trilho na prática

Referência é legal, mas o que importa é onde isso encaixa no teu dia

• Projeto do zero, escopo indefinido: brainstorming pra fechar o design e writing-plans pra virar arquitetura, com o plano em docs/superpowers/plans/ pra tu conferir depois
• Feature sem sujar o branch principal: using-git-worktrees, que além de criar o branch novo instala as dependências e roda a suíte pra tu saber se a linha de base já estava quebrada antes de tu encostar no código
• Bug que já resistiu a duas tentativas de tentativa e erro: systematic-debugging, com as quatro fases em ordem e o teste de reprodução obrigatório
• Fechar o trabalho sem esquecer nada: finishing-a-development-branch, que roda a suíte completa do projeto (npm test, cargo test, pytest, go test ./...) e, se falhar, reporta e PARA

Nesse fechamento a skill apresenta exatamente quatro opções: merge local, abrir pull request, manter o branch como está, ou descartar com confirmação

E a limpeza (git worktree remove e git worktree prune) só acontece se o caminho estiver sob .worktrees/ ou worktrees/, ou seja, ela mexe apenas nos worktrees que o próprio Superpowers criou

Um cuidado que eu achei bem pensado, porque os rm -rf da vida em pasta alheia é o tipo de coisa que a gente não perdoa

E se tu chegou na documentação querendo ESTENDER o framework, e não só usar, o caminho é a skill writing-skills mais a seção de criação de skills da wiki, que tem até uma subseção de test-driven development aplicado a skills

Como instalar no Claude Code, se tu decidir testar

A instalação é por comandos de barra dentro da própria sessão: primeiro tu registra o marketplace, depois instala o plugin

/plugin marketplace add obra/superpowers-marketplace
/plugin install superpowers@superpowers-marketplace

Repara no detalhe que já falei lá em cima: o nome do marketplace tem o sufixo -marketplace e vive em repositório separado do plugin

Errou o nome, não instala

O que aconteceu quando rodei esse fluxo

Eu li a documentação das skills antes de instalar qualquer coisa, justamente pra saber o que ia rodar na minha máquina

Depois rodei o brainstorming numa pasta vazia

E a skill fez o que a documentação promete: veio com uma sequência de perguntas sobre escopo (uso pessoal ou múltiplos usuários, tipo de autenticação, stack) antes de escrever UMA linha de código

Antes das perguntas, ela ainda ofereceu montar mockups e diagramas no navegador, avisando que o recurso era novo e podia consumir mais tokens

Recusei pra ir direto pra implementação

Dica sincera: responde essas perguntas com seriedade, porque a qualidade do documento final depende inteirinha das tuas respostas

No fim do brainstorm veio o documento de especificação, eu revisei, aprovei, e só então encadeei a skill de plano pedindo tarefas em ordem, dependências e critérios de aceitação

Pra execução eu pedi explicitamente subagents e TDD (teste antes da implementação)

Agora os números pra tu calibrar expectativa

O plano de implementação do app de despesas gerou 14 tarefas, e quando o agente ainda estava na TERCEIRA tarefa a execução já rodava havia quase 10 minutos

Ou seja: quem lê a documentação e imagina algo instantâneo vai tomar um susto

Outro detalhe operacional que me poupou dor de cabeça: referenciar o arquivo do plano com @ pra garantir que o Claude Code execute o documento certo, em vez de confiar só no contexto

Durante a execução foi confirmação atrás de confirmação, então vale considerar o modo de pular aprovações na fase de criação de arquivos e setup

E não, não saiu perfeito de primeira: o app subiu, mas o cadastro quebrou (ao criar conta eu era jogado pro login e tomava erro)

Colei o erro no chat, o Claude Code corrigiu, e aí sim o fluxo de autenticação funcionou

O resultado visual veio genérico, aquele projeto sem alma, e eu resolvi com uma skill de design de frontend usando um prompt que descrevia sensação (visual clean, modo escuro, sensação de controle financeiro) em vez de pedir componente

Mudou tipografia, cor de acento, cards, barra de navegação e animações, e ficou bem mais consistente

Sendo honesto: essa skill pode ou não gerar mudança significativa, e boa parte do resultado ruim que o pessoal reclama por aí vem de prompt fraco mesmo

Resumo do que aconteceu: o fluxo entregou o app funcionando, mas cobrou paciência no caminho, e o ganho real veio do plano, não da mágica

No vídeo abaixo eu mostro esse fluxo rodando na tela, do brainstorm até o app funcionando:

Vale adotar o Superpowers depois de ler a documentação?

Depende do que tu procura, então bora ser direto

A documentação entrega bem pra quem quer um fluxo opinativo de verdade: os dois portões de aprovação estão descritos, o protocolo de quatro fases do systematic-debugging está descrito, e o fechamento de branch tem princípio explícito (verificar testes, detectar ambiente, apresentar opções, executar e limpar)

Isso é raro em projeto de skill agêntica, que normalmente entrega um monte de arquivo solto e boa sorte

Onde exige cautela: a wiki mais completa é gerada por IA pela Cognition AI, não escrita pelo autor do projeto

Ela serve pra mapear rápido o que existe, mas na hora de confiar em comportamento específico de uma skill, o SKILL.md no repositório, o RELEASE-NOTES.md e a aba de Releases são a fonte final

E tem o custo real: esse fluxo consome mais tokens e demora mais

Eu defendo a troca porque o plano cobre pontos que eu não teria pensado sozinho, mas não é bala de prata e ninguém precisa fingir que é

Conclusão

Se tu chegou aqui procurando a Superpowers wiki, o roteiro de leitura é esse: página de referência de skills pra ter o mapa, depois os arquivos SKILL.md do repositório pra confirmar o comportamento de cada uma

Só DEPOIS disso tu decide instalar, com os dois comandos de barra que mostrei ali em cima

Lembrando do detalhe que confunde muita gente: o plugin clona as skills da comunidade pra ~/.config/superpowers/skills/, então é lá que tu vai olhar quando quiser ver (ou editar) o que foi parar na tua máquina

Lê primeiro, instala depois, e tu vai economizar um bom tempo de confusão 🙂

até o próximo post!