O que é uma skill do Superpowers e por que elas foram feitas para se combinar

Fala aí, beleza? Tem MUITA gente tratando skill como se fosse prompt salvo num arquivo de texto, e é aí que a coisa desanda

Superpowers é um framework de skills agentivas e metodologia de desenvolvimento, criado por Jesse Vincent (o handle dele no GitHub é obra), descrito no próprio repositório como "An agentic skills framework & software development methodology that works"

E a sacada que quase ninguém conta: essas skills não foram desenhadas pra viver sozinhas

Elas foram feitas pra se encadear, uma chamando a próxima, e é isso que a gente vai destrinchar aqui 🙂

Como uma skill é montada por dentro: SKILL.md e divulgação progressiva

Cada skill do Superpowers vive como uma pasta própria dentro do diretório skills/ do repositório, e dentro dela tem um arquivo SKILL.md

O padrão é esse: skills/<nome-da-skill>/SKILL.md

Dá pra ver isso em skills/writing-plans/SKILL.md e em skills/using-superpowers/SKILL.md, por exemplo

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

O que tem dentro do SKILL.md:

O arquivo começa com um frontmatter YAML e depois vira Markdown normal, com as instruções

Dois campos são obrigatórios:

• name: só minúsculas, números e hífens
• description: explica o que a skill faz E quando usar

Repara que a description não é enfeite

Ela é o que faz o agente decidir se aquela skill entra ou não na jogada

E por que 20 skills instaladas não entopem o contexto?

Aqui entra a divulgação progressiva, que funciona em três camadas

Descoberta: no início, só name e description entram no contexto

Ativação: o SKILL.md completo só carrega quando a skill é acionada

Execução: scripts, references e assets só chegam quando são necessários de verdade

Se você conhece lazy loading de imagem numa página web, é bem parecido: nada carrega antes da hora

É por isso que várias skills conseguem coexistir sem transformar seu contexto num monstro

As skills do Superpowers e a etapa do ciclo que cada uma cobre

Olhando a listagem do diretório skills/, dá pra perceber o desenho: a cobertura é por ETAPA do ciclo de desenvolvimento, não por tarefinha solta

Essas são skills existentes no repositório, entre outras

E o padrão da tabela já entrega o recado: tem uma skill pra cada momento do trabalho, do desenho até fechar a branch

Por que elas foram feitas para se combinar: o encadeamento é escrito na própria skill

Agora o ponto central

O encadeamento NÃO depende de você lembrar qual vem depois de qual

Ele está escrito dentro dos arquivos

A skill writing-plans determina que a implementação do plano seja feita por outra skill: superpowers:subagent-driven-development (que é a recomendada) ou superpowers:executing-plans, tarefa a tarefa

Ou seja: você termina o plano e a própria skill aponta a próxima etapa

E quem decide qual skill entra?

A using-superpowers cuida disso

Ela define que o agente cheque se existe uma skill relevante antes de começar a tarefa, anuncie qual skill vai usar e pra quê, e então siga o que a skill manda

E tem uma regra de ordem que eu acho mto boa: quando mais de uma skill se aplica, as process skills vêm primeiro (são elas que definem a abordagem) e as implementation skills executam depois

É a diferença entre decidir COMO fazer e sair fazendo

O fim da linha também é escrito

A finishing-a-development-branch fecha o ciclo com uma sequência fixa: verificar testes, detectar o ambiente, apresentar opções, executar a escolha, limpar

E as opções apresentadas são quatro, um conjunto fechado:

• merge local
• abrir pull request
• manter a branch como está
• descartar, com confirmação

Sacou o desenho? Começo, meio e fim, cada etapa entregando pra próxima

Como instalar o Superpowers e ver as skills disponíveis

No Claude Code, a instalação é feita em dois comandos

1. Adicione o marketplace

/plugin marketplace add obra/superpowers-marketplace

O erro comum deste passo: pular ele e tentar instalar o plugin direto

Sem o marketplace adicionado antes, o próximo comando não tem de onde puxar o plugin

2. Instale o plugin

/plugin install superpowers@superpowers-marketplace

Depois dos dois comandos, confira no /help:

/help

Depois de instalado, o plugin expõe comandos com o prefixo superpowers, e o /help é onde tu confere isso

Devem aparecer /superpowers:brainstorm, /superpowers:write-plan e /superpowers:execute-plan

Se apareceu, tá valendo 😀

Como a cadeia se comporta na prática

No vídeo abaixo eu mostro seis skills que eu uso nos meus projetos, e eu montei ele DE PROPÓSITO em sequência

São essas seis, na ordem em que aparecem: brainstorm, escrever plano, executar o plano com subagents, TDD, design de front end e criar uma skill própria

Porque skill isolada tu até entende no papel, mas o que elas entregam juntas só aparece quando uma puxa a outra

Um aviso antes de tu assistir: no vídeo sou EU chamando cada etapa na mão, uma de cada vez, e isso é escolha de didática, pra tu ver skill por skill separada

O que já vem escrito nos arquivos é QUAL etapa vem depois de qual, e é isso que tu enxerga acontecendo na saída de cada skill

Comecei numa pasta vazia, com o VS Code aberto e o Claude Code do lado, e acionei o brainstorm antes de descrever qualquer coisa

O projeto era um app de controle de despesas pessoais: cadastro de gasto por categoria, dashboard com resumo mensal e gráfico por categoria, com a stack já definida no prompt

E olha que interessante: a skill de brainstorm não saiu escrevendo código

Ela começou fazendo várias perguntas pra entender o projeto e tirar dúvidas antes de decidir qualquer coisa

Minha recomendação aqui é séria: responde cada pergunta com sinceridade, porque é isso que define a qualidade do que vem depois

No fim veio um resumo pra aprovar e depois uma documentação de especificações, que tu PRECISA ler e conferir antes de seguir

Do documento pro plano, e do plano pra execução

Daí eu emendei a segunda skill, a de escrever plano, pedindo que ela pegasse o documento de design aprovado e transformasse em plano de implementação com tarefas em ordem, dependências e critérios de aceitação

A saída foi um plano detalhado, com as tarefas quebradas uma a uma: 14 tarefas no meu teste

Dá pra pedir a execução direto porque o plano já está no contexto, mas eu prefiro marcar o arquivo com @ pra ter certeza de que o Claude vai executar AQUELE documento

Na execução eu pedi que o plano rodasse com subagents e TDD, teste primeiro e implementação depois, que é justamente o caminho que a skill de escrever plano já indica na saída dela

Tome cuidado com uma coisa: a fase de criação de arquivos e setup pede muitos aceites em sequência, talvez valha usar o modo de pular as confirmações

E demora, viu? Quando eu mostrei a terceira tarefa, a execução já estava rodando havia quase 10 minutos

Gasta mais token também

Mas eu achei o resultado mais certeiro, porque cobre coisa que eu não teria pensado lá no início

E deu tudo certo de primeira?

Não, e tá tudo bem

Ao abrir o projeto no navegador, o cadastro me mandou pro login e apareceu um erro

Colei o erro no chat pedindo análise e correção, e isso pra mim é normal em prompt inicial

Depois da correção o app abriu, lancei uma despesa de alimentação e confirmei que cadastro e autenticação estavam funcionando

As primeiras skills me deram um projeto com arquitetura boa, só que a interface saiu genérica

Projeto sem alma, como eu chamo haha

Aí eu emendei uma skill de design de front end (essa não é do Superpowers) pedindo redesenho com visual clean, modo escuro e sensação de controle financeiro, e mudou tipografia, estilos e consistência dos elementos

Ressalva honesta: isso pode não acontecer sempre, e boa parte das reclamações de resultado ruim vem de prompt mal escrito

Por último eu mostrei criar uma skill própria por prompt, uma verificação de segurança com nota de 0 a 100, checagem mecânica rodando comandos reais e contagem de problemas, criada como skill do projeto e não global

Eu prefiro segurança feita sob medida pro projeto, mesmo mandando o Claude criar, em vez de instalar uma pronta: fica alinhada às tecnologias e às regras daquele projeto

E nada disso é bala de prata, tá? É o que eu uso no dia a dia

Onde ficam suas próprias skills hoje (e o caminho que morreu)

Esse detalhe operacional evita dor de cabeça

No Claude Code, as skills pessoais (as que não vêm do plugin) ficam em ~/.claude/skills/

Codex, Copilot CLI e Gemini CLI também reconhecem ~/.agents/skills/ como alias entre runtimes

E tem o caminho que morreu: o repositório obra/superpowers-skills, das skills editáveis pela comunidade, foi arquivado pelo dono em 27/10/2025 e ficou read-only

Skills customizadas em ~/.config/superpowers/skills não são mais lidas

Se as tuas ainda estão lá, move pra ~/.claude/skills

Já me ferrei uma vez achando que algo não carregava por bug, quando era só caminho velho…

O projeto segue vivo, aliás: a v6.3.0 saiu em 12/08/2026, descrita como o maior release desde a v6.0

Conclusão

Se tu levar uma coisa só daqui, leva essa: a unidade de valor não é a skill, é a CADEIA

Uma skill do Superpowers sozinha resolve um pedaço, e olhe lá

O ganho aparece quando o brainstorm vira documento, o documento vira plano com dependências e critérios, o plano vira execução tarefa a tarefa, e o ciclo fecha na branch

E o mais massa é que essa ordem não depende da tua memória: ela está escrita dentro dos arquivos, com writing-plans mandando usar superpowers:subagent-driven-development ou superpowers:executing-plans

O próximo passo é bem concreto: instala, roda /superpowers:brainstorm e deixa a corrente te levar até o plano e a execução

Bora testar? até o próximo post!