Claude Skills para desenvolvimento: como criar, organizar e usar Skills no fluxo real de engenharia

A primeira vez que uma Skill fez sentido para mim não foi lendo documentação. Foi olhando para uma repetição.

O time revisava pull requests sempre com os mesmos critérios, mas o resultado variava muito. Um reviewer olhava arquitetura. Outro olhava teste. Outro se preocupava mais com segurança. Quando o prazo apertava, a revisão virava uma passada rápida para ver se o código “parecia certo”.

Com Claude acontecia algo parecido. Quando alguém pedia “revise essa PR”, a resposta dependia muito da qualidade do pedido. Se a pessoa detalhava arquitetura, riscos, testes, autenticação, banco de dados e padrão do projeto, o Claude entregava uma análise melhor. Se o pedido vinha seco, a resposta também vinha mais rasa.

Foi aí que a utilidade das Skills ficou mais clara.

Skill não é apenas prompt salvo.

Também não é um bloco bonito de instruções para deixar o projeto mais organizado.

No uso profissional, uma Skill é uma forma de transformar uma tarefa recorrente em uma capacidade reutilizável. Ela ensina o Claude a executar um tipo de trabalho com critérios mais estáveis, menos dependente de quem está pedindo e mais alinhado ao processo do time.

Para desenvolvimento, isso muda bastante a rotina.

Em vez de explicar toda vez como revisar uma PR, você cria uma Skill de revisão. Em vez de repetir como o time escreve testes, cria uma Skill de testes. Em vez de colar um log e esperar que o Claude adivinhe o que procurar, cria uma Skill de análise de incidentes ou falha de pipeline.

O ganho não está em “automatizar o desenvolvedor”.

O ganho está em reduzir variação, capturar conhecimento operacional e fazer o Claude trabalhar com um método mais parecido com o que o time espera.

Skill boa nasce de repetição

Eu não começaria criando uma biblioteca enorme de Skills.

Esse é um caminho tentador, principalmente quando a ferramenta parece poderosa. Dá vontade de criar Skill para tudo: backend, frontend, banco, DevOps, segurança, documentação, produto, arquitetura, testes, incidentes e mais uma dúzia de coisas.

Na prática, isso costuma gerar um diretório cheio de arquivos bonitos que ninguém usa.

O melhor ponto de partida é observar a repetição.

Se o time pede a mesma análise toda semana, ali existe uma candidata forte a Skill.

Alguns exemplos em desenvolvimento:

1. Revisão de pull request backend.
2. Criação de testes unitários.
3. Análise de falha de pipeline.
4. Revisão de migration de banco de dados.
5. Investigação de logs de produção.
6. Documentação de endpoint de API.
7. Refatoração segura de código legado.
8. Revisão de autenticação e autorização.

Se a tarefa é rara, um bom prompt resolve.

Se a tarefa volta toda semana, vale transformar em processo.

Essa é a diferença.

Prompt, CLAUDE.md e Skill têm papéis diferentes

Uma confusão comum é jogar tudo dentro do prompt.

A pessoa abre o Claude e escreve um pedido enorme: explica a stack, descreve a arquitetura, cola os comandos, define o padrão de teste, explica como revisar, diz o que não pode alterar e, no final, pede a tarefa.

Funciona uma vez. Depois cansa.

Em um fluxo mais organizado, cada camada tem uma função.

1. O CLAUDE.md explica o projeto.
2. A Skill explica como executar um tipo de trabalho.
3. O prompt explica qual é a tarefa atual.

Um exemplo simples:

1. O CLAUDE.md diz que o projeto usa Node.js, TypeScript, PostgreSQL, Jest e arquitetura com controllers, services e repositories.
2. A Skill de revisão backend define como avaliar segurança, testes, arquitetura, banco de dados e contrato de API.
3. O prompt do usuário diz: “Revise esta PR que altera o fluxo de autenticação”.

Quando essa separação existe, a conversa fica menor e a resposta tende a ser mais consistente.

O CLAUDE.md responde: onde estou?

A Skill responde: como devo trabalhar neste tipo de tarefa?

O prompt responde: o que precisa ser feito agora?

Como uma Skill é organizada

Uma Skill normalmente fica em uma pasta própria e tem um arquivo principal chamado SKILL.md.

Esse arquivo descreve quando a Skill deve ser usada, qual é o objetivo da tarefa, qual processo o Claude deve seguir e como a resposta deve ser entregue.

Uma estrutura simples pode ser assim:

code-review-backend/
SKILL.md
examples/
good-review.md
bad-review.md
references/
security-checklist.md
testing-guidelines.md

Nem toda Skill precisa de exemplos, referências ou arquivos auxiliares.

Na maioria dos casos, eu começaria apenas com o SKILL.md. Depois, se a Skill se mostrar útil, adicionaria exemplos reais, checklists e referências internas.

Começar simples facilita a manutenção.

Uma Skill muito grande logo na primeira versão geralmente vira um manual difícil de usar. O ideal é criar uma primeira versão curta, testar em trabalho real e melhorar com base no que deu errado.

Exemplo prático: Skill de revisão de código backend

Revisão de código é uma das primeiras Skills que eu criaria em um time de desenvolvimento.

É uma tarefa recorrente, exige consistência e sofre bastante com pressa. Além disso, uma boa revisão não olha apenas se o código compila. Ela olha impacto, teste, regra de negócio, segurança, contrato de API, banco de dados e manutenção futura.

Um SKILL.md inicial poderia ser assim:

name: code-review-backend

description: Use esta Skill para revisar alterações backend, especialmente em APIs, services, repositories, autenticação, autorização, banco de dados e regras de negócio.

Code Review Backend

Objetivo

Ajudar o reviewer humano a identificar riscos técnicos antes do merge.

Quando usar

Use esta Skill quando houver alteração em código backend, APIs, regras de negócio, autenticação, autorização, banco de dados, jobs, filas ou integrações.

Processo

1. Entenda o objetivo da alteração.
2. Identifique os arquivos modificados.
3. Verifique se a alteração respeita a arquitetura do projeto.
4. Procure regras de negócio colocadas no lugar errado.
5. Avalie riscos de autenticação e autorização.
6. Verifique se existem testes suficientes.
7. Avalie impacto em performance e banco de dados.
8. Identifique mudanças de contrato de API.
9. Sugira correções objetivas.
10. Separe problemas críticos de melhorias opcionais.

Critérios

Avalie:

1. Segurança.
2. Testes.
3. Legibilidade.
4. Acoplamento.
5. Tratamento de erros.
6. Compatibilidade com padrões do projeto.
7. Impacto em dados existentes.
8. Impacto em usuários finais.

Formato da resposta

Responda com:

1. Resumo da alteração.
2. Riscos críticos.
3. Pontos de atenção.
4. Testes ausentes ou frágeis.
5. Sugestões de melhoria.
6. Perguntas para o autor da PR.
7. Recomendação final para o reviewer humano.

Perceba o detalhe: a Skill não pede apenas “revise o código”.

Ela define o que observar, em que ordem pensar e como devolver a análise.

Essa estrutura tira a revisão do improviso.

Case: PR revisada com critérios mais estáveis

Imagine uma PR que altera o fluxo de autenticação de uma API.

Sem Skill, o Claude pode focar no trecho mais visível do código e ignorar efeitos laterais. Pode comentar estilo, mas deixar passar ausência de teste para token expirado. Pode elogiar a organização, mas não questionar autorização em endpoints sensíveis.

Com uma Skill de revisão backend, o comportamento muda.

O fluxo poderia ser:

1. O desenvolvedor abre a PR.
2. Claude lê o diff.
3. A Skill de revisão backend é acionada.
4. Claude separa riscos críticos de melhorias opcionais.
5. Claude aponta testes ausentes.
6. Claude levanta perguntas para o autor da PR.
7. O reviewer humano usa a análise como apoio.

O reviewer continua decidindo.

A Skill apenas evita que a primeira análise dependa tanto do humor, da pressa ou da experiência de quem está revisando.

Em times com muita PR pequena, esse apoio já reduz bastante esquecimento.

Exemplo prático: Skill de criação de testes

Muitos times dizem que querem mais testes. Poucos conseguem manter isso de forma disciplinada quando a sprint aperta.

Com Claude, o risco é outro: pedir “crie testes” e receber uma bateria de testes que aumenta cobertura, mas protege pouco.

Teste útil não é só teste que passa.

Teste útil protege comportamento relevante.

Uma Skill de testes precisa orientar o Claude a buscar regra de negócio, casos de borda, regressões e efeitos colaterais.

name: test-writer

description: Use esta Skill para criar ou melhorar testes automatizados em código existente, priorizando regras de negócio, casos de borda e regressões.

Test Writer

Objetivo

Criar testes úteis, legíveis e alinhados ao comportamento real do sistema.

Quando usar

Use quando o usuário pedir criação de testes, melhoria de cobertura, proteção contra regressão ou validação de uma correção de bug.

Processo

1. Entenda o comportamento esperado.
2. Identifique entradas, saídas e efeitos colaterais.
3. Liste cenários principais.
4. Liste casos de borda.
5. Identifique dependências externas.
6. Prefira testes pequenos e legíveis.
7. Evite testar detalhes internos sem necessidade.
8. Crie testes que falhariam se o bug voltasse.
9. Explique como executar os testes.

Prioridade dos testes

1. Regra de negócio crítica.
2. Bug corrigido recentemente.
3. Fluxos de autenticação e autorização.
4. Cálculos ou validações sensíveis.
5. Integrações com efeitos colaterais.
6. Casos de erro previsíveis.

Formato da resposta

1. Cenários identificados.
2. Testes criados ou sugeridos.
3. Arquivos alterados.
4. Como executar.
5. Limitações da cobertura.

Essa Skill impede um problema comum: o Claude sair testando detalhe interno só porque é fácil.

O foco passa a ser comportamento.

Case: código legado com baixa cobertura

Código legado é um bom teste para qualquer Skill.

Em módulo legado, quase sempre existe regra misturada com infraestrutura, dependência escondida, efeito colateral e acoplamento. Pedir simplesmente “crie testes para esse módulo” costuma gerar uma resposta frágil.

Uma Skill de testes mais madura faria o Claude seguir outra sequência:

1. Identificar o comportamento público do módulo.
2. Separar regra de negócio de infraestrutura quando possível.
3. Mapear os fluxos principais.
4. Mapear bugs conhecidos.
5. Criar testes de caracterização antes de refatorar.
6. Propor refatorações pequenas depois que o comportamento estiver protegido.

Esse tipo de orientação evita a pressa de refatorar antes de proteger.

Em legado, essa pressa custa caro.

Exemplo prático: Skill de análise de incidentes

Quando algo quebra em produção, a conversa tende a ficar bagunçada.

Alguém cola um pedaço do log. Outra pessoa lembra de uma mudança feita ontem. Um terceiro sugere reiniciar o serviço. Em poucos minutos, todo mundo está olhando para sintomas diferentes.

Uma Skill de incidente ajuda o Claude a organizar a investigação.

Ela força separação entre sintoma, evidência, hipótese, impacto e ação.

name: incident-analysis

description: Use esta Skill para analisar erros de produção, falhas de pipeline, alertas, logs e comportamento inesperado em sistemas.

Incident Analysis

Objetivo

Ajudar o time a entender rapidamente o que está acontecendo, qual o impacto provável e quais ações tomar.

Processo

1. Separar sintomas de causa provável.
2. Identificar serviço ou componente afetado.
3. Procurar evidências nos logs.
4. Verificar mudanças recentes.
5. Classificar impacto.
6. Propor mitigação imediata.
7. Propor correção definitiva.
8. Indicar como prevenir recorrência.

Classificação da causa

Classifique a hipótese principal como:

1. Código.
2. Ambiente.
3. Dependência externa.
4. Banco de dados.
5. Infraestrutura.
6. Configuração.
7. Credencial ou permissão.
8. Carga ou concorrência.

Formato da resposta

1. Resumo do incidente.
2. Impacto provável.
3. Evidências encontradas.
4. Causa mais provável.
5. Hipóteses alternativas.
6. Ação imediata.
7. Correção definitiva.
8. Prevenção de recorrência.

Sem esse tipo de estrutura, a resposta tende a ficar vaga: “parece ser problema de conexão”, “verifique as variáveis de ambiente”, “rode os testes novamente”.

Com a Skill, o Claude precisa mostrar o raciocínio operacional.

Case: falha de pipeline

Um caso comum: o pipeline falha depois de uma alteração pequena.

O desenvolvedor olha a última linha do log, tenta corrigir o que aparece ali e roda de novo. Às vezes resolve. Muitas vezes não, porque a primeira causa relevante estava cinquenta linhas acima.

Com uma Skill de pipeline ou incidente, o Claude pode seguir uma análise mais útil:

1. Identificar em qual etapa o pipeline falhou.
2. Separar erro de build, teste, lint, dependência ou ambiente.
3. Localizar a primeira mensagem relevante do log.
4. Verificar relação com a alteração recente.
5. Classificar a causa provável.
6. Sugerir a menor correção segura.

Não é uma investigação perfeita, mas reduz tentativa e erro.

Como criar uma boa Skill

Eu usaria um processo curto.

1. Escolha uma tarefa repetida.
2. Escreva o objetivo em uma frase.
3. Defina quando a Skill deve ser usada.
4. Descreva o processo em passos objetivos.
5. Defina o formato de resposta.
6. Teste com casos reais.
7. Ajuste com base nos resultados.

O primeiro passo parece óbvio, mas evita muita Skill inútil.

Não comece com uma Skill chamada “desenvolvimento”. Ela é ampla demais. Comece com algo concreto: revisão de PR backend, criação de testes para service, análise de migration, investigação de log, documentação de endpoint.

O objetivo precisa caber em uma frase.

Se não cabe, a Skill provavelmente está tentando resolver problemas demais.

A descrição de uso também merece cuidado. Ela ajuda o Claude a decidir quando aquela Skill deve entrar no fluxo. Uma descrição vaga pode fazer a Skill aparecer em tarefas erradas ou não aparecer quando deveria.

O processo deve orientar raciocínio, não decorar a resposta.

Em vez de escrever “avalie qualidade”, diga o que qualidade significa naquele contexto. Pode ser baixo acoplamento, teste de regressão, tratamento de erro, validação de permissão, compatibilidade com contrato de API ou impacto em banco.

Depois vem o teste real.

Pegue uma PR antiga, um log real, um bug já corrigido ou uma migration que deu problema. Rode a Skill e compare com o que o time esperaria de uma boa análise.

Esse teste costuma mostrar rapidamente onde a Skill está genérica demais.

Checklist para saber se a Skill ficou boa

Antes de colocar uma Skill no fluxo do time, eu faria esta checagem:

1. A Skill resolve uma tarefa recorrente?
2. O objetivo está claro?
3. A descrição ajuda o Claude a saber quando usar?
4. O processo tem passos objetivos?
5. O formato da resposta reduz ruído?
6. A Skill evita frases genéricas?
7. Ela respeita os padrões do projeto?
8. Ela deixa claro quando pedir aprovação humana?
9. Ela foi testada com exemplos reais?
10. Ela é curta o bastante para ser mantida?

Se vários itens falharem, a Skill ainda é rascunho.

Melhor ajustar antes de espalhar para o time.

Repositórios de Skills prontas

Dá para começar olhando repositórios públicos, mas eu usaria isso com cuidado.

O repositório público da Anthropic é um bom ponto de partida para entender organização, estrutura e exemplos de Skills. Também existem repositórios e listas da comunidade com Skills prontas ou coleções no estilo “awesome”.

Eu trataria esses materiais como referência, não como instalação automática.

Skill é instrução operacional. Em alguns casos, pode trazer arquivos auxiliares, scripts, padrões de comando ou orientações que influenciam como o Claude mexe no projeto.

Em ambiente profissional, eu seguiria esta sequência:

1. Use Skills públicas como inspiração.
2. Leia o SKILL.md antes de usar.
3. Verifique se existem scripts ou arquivos auxiliares.
4. Teste em um projeto descartável.
5. Adapte para os padrões do seu time.
6. Versione as Skills internas.
7. Evite Skills genéricas em projetos críticos.

Skills prontas ajudam no começo, mas o maior valor vem quando você adapta para o seu contexto.

Uma Skill pública não conhece seu legado, seus atalhos perigosos, seus padrões de teste, suas integrações nem suas restrições de produção.

Como organizar Skills em um time

Para uso individual, uma pasta local pode bastar.

Para equipe, eu prefiro um repositório interno.

Algo como:

team-claude-skills/
README.md
backend/
code-review/
SKILL.md
test-writer/
SKILL.md
incident-analysis/
SKILL.md
frontend/
component-review/
SKILL.md
accessibility-review/
SKILL.md
database/
query-review/
SKILL.md
migration-review/
SKILL.md
devops/
pipeline-debug/
SKILL.md
deploy-checklist/
SKILL.md

Essa estrutura ajuda o time a tratar Skills como parte do processo de engenharia.

Eu também colocaria revisão nas mudanças.

Uma Skill ruim pode fazer o Claude repetir uma análise ruim muitas vezes. Por isso, mudanças em Skills compartilhadas deveriam passar por revisão, principalmente quando afetam segurança, produção, banco de dados ou deploy.

Skills não são código de produção, mas influenciam decisões sobre código de produção.

Esse detalhe muda a forma de governar.

Skills específicas para desenvolvimento

Uma biblioteca inicial para um time de desenvolvimento poderia ter poucas Skills bem escolhidas.

1. Code Review Backend.
2. Code Review Frontend.
3. Test Writer.
4. Bug Reproduction.
5. Incident Analysis.
6. SQL Review.
7. Migration Review.
8. API Documentation.
9. Refactoring Plan.
10. Security Review.

O segredo está no recorte.

Uma Skill de SQL Review não precisa revisar toda a arquitetura do sistema. Ela deve olhar consulta, índice, filtro, join, paginação, lock, risco de full scan e impacto em volume grande de dados.

Uma Skill de Migration Review deve olhar rollback, compatibilidade com dados existentes, alteração destrutiva, tempo de lock, deploy em múltiplas etapas e impacto em versões antigas da aplicação.

Uma Skill de API Documentation deve olhar contrato, exemplos de request e response, códigos de erro, autenticação, paginação, filtros e compatibilidade.

Quanto mais claro o recorte, melhor a resposta.

O que evitar ao criar Skills

Alguns erros aparecem rápido.

O primeiro é criar Skills genéricas demais.

Uma Skill chamada “developer-helper” provavelmente vira um saco de instruções misturadas. Ela tenta revisar código, criar testes, explicar arquitetura, debugar log e documentar API ao mesmo tempo. No fim, não faz nada muito bem.

O segundo é colocar regra demais.

Se a Skill vira um manual enorme, o time deixa de manter. Skill boa precisa ser objetiva.

O terceiro é não testar.

Skill que nunca foi usada em PR real, bug real ou log real ainda é hipótese.

O quarto é copiar Skill pronta sem adaptação.

Uma Skill pública pode ser ótima inspiração, mas seu projeto tem arquitetura, riscos, comandos e padrões próprios.

O quinto é não versionar.

Se a Skill muda sem histórico, fica difícil entender por que o comportamento do Claude mudou.

Um fluxo realista para começar

Eu começaria com um piloto pequeno.

1. Escolha uma tarefa recorrente, como revisão de PR backend.
2. Crie uma primeira versão da Skill.
3. Teste em três PRs antigas.
4. Compare a análise do Claude com os comentários humanos que já aconteceram.
5. Ajuste a Skill para reduzir respostas genéricas.
6. Use em PRs novas durante uma semana.
7. Peça feedback dos reviewers.
8. Versione a Skill revisada.
9. Só depois crie a próxima Skill.

Esse caminho evita a armadilha de criar uma biblioteca inteira antes de saber se o time vai usar.

Também cria confiança aos poucos.

Quando uma Skill ajuda em uma PR real, o time percebe valor. Quando ela apenas existe em uma pasta, vira documentação morta.

Conclusão

Skills são uma das formas mais práticas de transformar Claude em apoio real para desenvolvimento.

Elas reduzem repetição, padronizam análises e ajudam o time a reaproveitar conhecimento operacional.

O valor não está em escrever uma Skill bonita.

O valor está em capturar uma tarefa recorrente, transformar em processo claro, testar em casos reais e melhorar com o uso.

Prompt resolve a conversa de agora.

Skill melhora o trabalho que volta toda semana.

Quando combinadas com CLAUDE.md, Hooks, Subagents, MCP e uma camada de Harness, as Skills deixam de ser apenas instruções reutilizáveis e começam a fazer parte da infraestrutura de engenharia do time.

O caminho mais seguro é começar pequeno, validar no fluxo real e transformar repetição em capacidade.