Como criar uma skill de revisão de código no Claude Code com os critérios do seu time

Fala aí, beleza? Pedir "revisa meu código" pro Claude Code devolve uma revisão bonita, educada e completamente genérica

Ela não sabe que o teu time exige teste pra todo caso de erro, que aquela pasta de domínio não pode importar nada de infra, que erro esperado ali vira retorno tipado e não exceção solta

A saída pra isso é uma skill de revisão de código no Claude Code: uma pasta com um arquivo SKILL.md dentro, carregando o checklist real do teu time, versionada junto com o repositório

Skills no Claude Code são baseadas em arquivos, e o caminho é literalmente esse: ~/.claude/skills/<nome>/SKILL.md pra skill pessoal (vale em todos os teus projetos) ou .claude/skills/<nome>/SKILL.md pra skill do projeto (vai pro Git e chega em quem clonar)

Nesse post a gente monta uma do zero, com os teus critérios dentro, e depois vê como distribuir pro time inteiro

Bora? 😀

O que você precisa antes de criar a skill

A lista é curta, nada de PC da Nasa aqui:

• Claude Code instalado e rodando no teu terminal
• Acesso de escrita ao repositório do projeto, se você vai criar a skill em .claude/skills/ (o caminho que dá pra versionar)
• Ou o teu diretório pessoal, se a skill for em ~/.claude/skills/ e valer pra todos os projetos
• O insumo principal: o checklist de code review do time

Esse último item é o que faz a skill valer alguma coisa

Pode estar num doc, numa wiki, no template de pull request do repositório ou só na cabeça do dev mais antigo

Se estiver na cabeça de alguém, tudo bem, mas você vai ter que arrancar isso de lá antes de escrever o arquivo, porque skill sem critério é só um prompt bonitinho

Skill pessoal ou skill do projeto?

A escolha muda quem enxerga a skill:

Pra checklist de time, projeto ganha fácil

O critério de revisão de um projeto Go não é o mesmo de um projeto Next, e a skill do projeto acompanha a stack daquele repositório

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

O plugin skill-creator (opcional)

Se você quiser uma mãozinha pra criar e avaliar skills, existe um plugin oficial chamado skill-creator, mantido no repositório anthropics/claude-plugins-official, na pasta plugins/skill-creator

Instalação no Claude Code:

/plugin marketplace add anthropics/claude-plugins-official
/plugin install skill-creator@claude-plugins-official

Se o resumo da instalação pedir, roda /reload-plugins pra ativar na sessão atual

O primeiro comando só é necessário se o marketplace ainda não estiver adicionado

E se liga: isso é opcional

Skill é pasta com arquivo markdown dentro, tu consegue fazer na unha com um editor de texto em dois minutos

Passo a passo: criando a skill de revisão de código

1. Crie a pasta e o arquivo

O nome da pasta é o identificador da skill: uma pasta .claude/skills/csv-analyzer/ com SKILL.md dentro define a skill csv-analyzer

   mkdir -p .claude/skills/code-review-time
   touch .claude/skills/code-review-time/SKILL.md

Chamei de code-review-time de propósito: o Claude Code já vem com um conjunto de skills embutidas, entre elas /code-review, /doctor, /debug e /verify

Usa um nome próprio do teu time, assim a tua skill não disputa espaço com o nome de uma embutida

O erro comum deste passo: criar o arquivo solto em .claude/skills/code-review.md, sem pasta

A estrutura é pasta com SKILL.md dentro, e o nome da pasta é o que identifica a skill

2. Escreva o frontmatter YAML

O SKILL.md começa com frontmatter YAML e tem dois campos obrigatórios: name e description

   ---
   name: code-review-time
   description: Revisa mudanças de código aplicando o checklist de code review do time, cobrindo fronteiras de módulo, tratamento de erro e cobertura de teste. Use quando o usuário pedir para revisar um PR, revisar um diff, fazer code review, ou avaliar mudanças antes de abrir pull request.
   ---

As regras dos campos são apertadas, então vale decorar

name: máximo 64 caracteres, apenas letras minúsculas, números e hífens, sem tags XML e sem palavras reservadas

description: máximo 1.024 caracteres, não pode ser vazia e sem tags XML

E por que a description importa tanto? Porque ela é o texto que o Claude compara com o teu pedido pra decidir se aciona a skill

Ela precisa dizer o que a skill faz E quando usar, escrita em terceira pessoa, com termos e gatilhos específicos ("revisar PR", "code review", os nomes das tecnologias do teu time)

Repara também que a description só promete o que o corpo entrega: se amanhã você adicionar uma seção de segurança no checklist, ela entra aqui junto

O erro comum deste passo: description vaga do tipo "ajuda com qualidade de código"

Aí você pede pra revisar o PR, o Claude não relaciona o pedido com a skill, ela não entra em contexto e você jura que a ferramenta é ruim

3. Escreva o corpo com os critérios do time

Aqui vai o checklist de verdade, e tem uma sutileza: a documentação oficial recomenda ajustar o grau de liberdade das instruções

Tarefa frágil pede script exato (baixa liberdade), tarefa aberta pede direção geral (alta liberdade)

E revisão de código é citada como exemplo de campo aberto sem perigos, em que o contexto determina a melhor abordagem

Ou seja: dá a direção, não escreve um fluxograma de 40 linhas

   ## Como revisar

   Leia o diff inteiro antes de comentar qualquer coisa
   Classifique cada achado em: bloqueia o merge, ajuste sugerido, ou nota informativa

   ## Critérios do time

   ### Fronteiras de módulo
   Nada dentro de `src/domain/` pode importar de `src/infra/`
   A dependência anda sempre de fora para dentro

   ### Tratamento de erro
   Erro esperado vira retorno tipado, não exceção solta
   `catch` vazio ou com log genérico bloqueia o merge

   ### Testes
   Todo caminho de erro novo precisa de teste do caminho de erro
   Teste que só verifica o caminho feliz conta como cobertura incompleta

Três seções, três critérios que o time cobra de verdade

Começa por esse tamanho e cresce depois, com o que aparecer nos PRs

O erro comum deste passo: escrever passo a passo rígido pra uma tarefa que pede julgamento

Se você amarra demais, a revisão vira preenchimento de formulário e ignora o problema real que estava ali do lado

4. Adicione exemplos de entrada e saída

Pra skills em que a qualidade do resultado depende de ver exemplos, a recomendação oficial é fornecer pares de entrada e saída dentro da própria skill

Revisão é exatamente isso: o modelo precisa ver o formato de comentário que o teu time considera útil

   ## Exemplo

   Entrada (trecho do diff):
   `const user = await db.query("SELECT * FROM users WHERE id = " + id)`

   Saída esperada:
   BLOQUEIA: concatenação de string em query
   Arquivo: src/infra/user-repo.ts
   Correção: usar query parametrizada, como já é feito em src/infra/order-repo.ts

Repara no detalhe: a saída aponta um arquivo do próprio repositório como referência de "o jeito certo aqui"

É isso que tira a revisão do modo genérico

O erro comum deste passo: exemplo inventado, com código que não existe no projeto

Puxa exemplo de PR real que já rolou, funciona muito melhor

5. Mova material longo para um arquivo de apoio

Dá pra colocar arquivos de apoio dentro da pasta da skill (um REFERENCE.md, por exemplo) e referenciá-los no SKILL.md, deixando o Claude decidir quando precisa carregar aquele material

Isso existe porque skills usam divulgação progressiva de contexto, em 3 níveis: só name e description de todas as skills são pré-carregados no system prompt na inicialização, o corpo do SKILL.md só entra quando a skill fica relevante, e arquivos extras e scripts só são lidos ou executados quando necessários

   .claude/skills/code-review-time/
   ├── SKILL.md
   └── REFERENCE.md

E no SKILL.md:

   Para o guia completo de estilo e as regras de segurança do time,
   consulte REFERENCE.md nesta mesma pasta

O erro comum deste passo: enfiar o guia de estilo inteiro, as regras de segurança e o histórico de decisões num SKILL.md gigante

O arquivo vira uma parede de texto e o critério importante se perde no meio

6. Salve e teste

O Claude Code monitora os diretórios de skills e capta mudanças de arquivo automaticamente quando você adiciona, edita ou remove uma skill em ~/.claude/skills/ ou no .claude/skills/ do projeto

Então salva o arquivo e testa com um pedido parecido com o que o time faria no dia a dia:

   revisa as mudanças desse branch usando o checklist do time

Se a skill não entrar, o suspeito número um é a description, não o corpo

Volta no passo 2 e coloca os gatilhos que você usa de verdade quando pede revisão

Que critérios entram na skill (e como priorizar)

Essa é a parte que separa uma skill útil de mais um arquivo morto no repositório

O que costuma valer a pena virar critério:

• Convenções de nomenclatura e estrutura do projeto (onde cada coisa mora, como se chama)
• Fronteiras de arquitetura (o que pode importar o quê)
• Regras de segurança próprias do stack (validação de entrada, manejo de segredo, autenticação)
• Padrões de teste (o que precisa de teste, que tipo de teste conta)
• Tratamento de erro (o que vira exceção, o que vira retorno, o que vira log)
• Regras de performance específicas daquela stack (aquela query que sempre é feita errada, aquele render que sempre re-renderiza)

O exemplo que a gente montou lá em cima pegou três desses

Os outros entram quando forem dor de verdade no teu repositório, e aí você atualiza a description junto

Como priorizar

Abre os PRs dos últimos meses e olha os comentários que mais se repetem

O que o time comenta toda semana é o critério que precisa estar na skill, porque é o gargalo real da revisão de vocês

E deixa de fora tudo que linter e formatter já pegam sozinhos

Indentação, aspas, ponto e vírgula, ordem de import: se a ferramenta já resolve no commit, colocar isso na skill só gasta contexto e enche o review de ruído

Como evitar revisão genérica

A regra é simples: critério com exemplo concreto do repositório, nunca "siga as boas práticas"

"Boas práticas" é a frase que gera aquele review de LinkedIn, cheio de conselho correto e inútil

Compara:

No extremo oposto dessa ideia tem gente fazendo revisão de código em uma linha, que é divertido e tem o seu uso, mas não é o que você quer quando o assunto é checklist de time

Quando quebrar em várias skills

Se o checklist ficou grande demais, quebra em skills separadas: uma de segurança, uma de arquitetura, uma de testes

Dá pra fazer isso com tranquilidade porque é a description que decide qual delas entra em contexto, então cada uma é acionada no pedido certo

É o mesmo raciocínio de montar uma skill de design para dashboards: critério específico, escopo específico, ativação específica

Como isso se comporta no uso real

Aqui eu falo do que eu vi na prática, e não do que a doc promete

No vídeo eu mostro o fluxo com as skills que uso em todos os meus projetos, e uma das etapas é justamente criar uma skill customizada dentro do próprio projeto

Pra análise de código eu prefiro skill sob medida em vez de baixar uma pronta

Existem skills prontas de segurança por aí, e podem até ser boas, mas eu gosto que os critérios estejam alinhados com o projeto que estou fazendo, porque cada projeto varia de tecnologia

O exemplo que eu crio ao vivo é uma skill de checagem de segurança que dá uma nota de 0 a 100 pro projeto

E o critério central que eu exijo no prompt de criação é que a verificação seja mecânica: a skill precisa rodar comandos reais e contar os problemas encontrados, em vez de só opinar

Ditei item a item o que ela deve checar (segredos expostos, entradas do usuário, autenticação, dependências, cabeçalhos), tudo em cima do que eu já vi dar problema na vivência

Se liga nisso: eu aceito pedir pro próprio Claude Code escrever a skill, desde que os critérios sejam ditados por mim no prompt

A skill do vídeo vale só naquele projeto, mas poderia ser feita como global, é a mesma ideia dos dois caminhos que a gente viu lá em cima

Outro detalhe que ajuda: quando eu quero garantir que o Claude Code use exatamente um documento, eu cito o arquivo com @ no prompt, em vez de confiar só no contexto da conversa

Expectativa de tempo e de escopo

Quando as skills entram no fluxo do dia a dia, o plano de implementação do projeto saiu com 14 tarefas, todas concluídas no final

E uma dessas tarefas ficou quase 10 minutos rodando

Então calibra a expectativa: não é resposta de chat, é execução longa

Eu leio a documentação e o plano produzidos e confirmo se é aquilo que eu queria antes de mandar executar, porque revisar depois de 14 tarefas rodadas dói bem mais

A execução eu peço com subagentes e TDD (teste primeiro, implementação depois), pro projeto sair testado

E mesmo com todo esse planejamento, o app quebrou no cadastro e no login na primeira execução

Resolvi colando o erro de volta no Claude Code pra analisar e corrigir

Porque skill não é bala de prata, e muita reclamação de resultado ruim vem de prompt mal escrito, não da ferramenta

No vídeo você vê essa skill customizada sendo criada do zero dentro do projeto, com os critérios ditados no prompt, e o fluxo inteiro rodando depois

Como distribuir a skill para o time inteiro

Skill boa que só existe na tua máquina é bala perdida, então tem duas rotas

Rota 1: commitar a pasta no repositório

A .claude/skills/ do projeto entra no controle de versão normalmente

git add .claude/skills/code-review-time
git commit -m "skill de code review com os criterios do time"

Quem clonar o repositório já tem a skill

E bônus: o checklist do time passa a evoluir por pull request, com discussão e histórico, igual código

Rota 2: marketplace de plugins no GitHub

Se você quer distribuir pra vários repositórios, dá pra publicar num marketplace de plugins hospedado no GitHub: um repositório com um arquivo .claude-plugin/marketplace.json

Os colegas adicionam assim:

/plugin marketplace add owner/repo

Pra fontes git é possível omitir a versão, e cada novo commit é tratado como versão nova

Dá também pra configurar o repositório do projeto pra que o Claude Code adicione o marketplace do time automaticamente quando o colega confia na pasta do projeto, via .claude/settings.json

Menos "instala isso aí" no Slack, mais coisa funcionando sozinha 🙂

Controle de quem invoca a skill

Por padrão, tanto você quanto o Claude podem invocar qualquer skill

O frontmatter permite apertar isso:

• disable-model-invocation: true: só o usuário invoca, indicado pra fluxos com efeito colateral, tipo /commit ou /deploy
• user-invocable: false: só o Claude invoca, indicado pra conhecimento de fundo

Pra uma skill de revisão, o padrão costuma ser o melhor: você chama quando quer, e o Claude também puxa sozinho quando o pedido bate com a description

Se o teu time prefere revisão só sob demanda, aí sim disable-model-invocation: true faz sentido

E vale saber: skill e comando personalizado são equivalentes no Claude Code

Um arquivo .claude/commands/deploy.md e uma skill em .claude/skills/deploy/SKILL.md criam o mesmo /deploy

Os arquivos que você já tem em .claude/commands/ continuam funcionando, e as skills só somam recursos opcionais: diretório de arquivos de apoio, frontmatter de controle de invocação e carregamento automático pelo modelo

Conclusão

A skill não vale pelo arquivo, vale pelo checklist que tem dentro dele

A pasta com SKILL.md, o frontmatter com name e description, o REFERENCE.md de apoio: isso é encanamento, você monta em dez minutos

O que faz a revisão parar de ser genérica é o critério ancorado no teu repositório, com exemplo de entrada e saída que o teu time reconhece

Próximo passo, bem concreto: abre os últimos PRs revisados, extrai os três comentários que mais se repetem e transforma eles no teu primeiro SKILL.md

Commita junto com o projeto e deixa o checklist do time evoluir versionado, igual código

Depois volta e me conta o que a tua skill pegou que passava batido…

até o próximo post! 😀