Skill de testes no Claude Code: o que ela precisa saber do seu projeto

Fala aí, beleza? Você pede um teste, o Claude devolve um arquivo com nome fora do padrão da pasta, asserção num estilo que ninguém usa ali, e um mock de um módulo que não precisava ser mockado…

O teste até roda

Mas ninguém quer aquilo no repositório

A skill de testes no Claude Code é, na prática, uma pasta com um arquivo SKILL.md: frontmatter YAML mais instruções em Markdown, podendo levar junto arquivos de apoio (scripts, templates, referências). O mecanismo é simples. O que separa saída aproveitável de saída descartável é OUTRA coisa: o contexto de projeto que você escreve dentro dela

E esse é o ponto: com o contexto certo dentro da skill, o teste já sai no padrão da casa no primeiro pedido, sem aquela rodada de conserto na mão depois

Este guia mostra qual informação levantar do seu projeto e onde colocar cada uma: o que vai no SKILL.md, o que vai em arquivo de apoio e o que na verdade era memória de projeto

Antes de criar a skill: o que ter em mãos

Duas coisas: o Claude Code instalado e clareza sobre qual é o padrão de teste que você quer ver saindo

Esse segundo ponto não é detalhe. A skill não inventa o padrão do seu time, ela repete um padrão que você aponta. Se já existe um arquivo de teste bom no repositório, ótimo, ele vira sua referência viva. Se não existe, escreva UM arquivo do jeito certo e use ele de modelo, que já resolve

Antes de embrulhar tudo numa skill, vale ter clareza sobre o que dá pra delegar em testes e o que você confere na mão depois

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

Onde a skill vai viver:

No Claude Code as skills são baseadas em sistema de arquivos, em dois lugares:

• ~/.claude/skills/ para as suas skills pessoais
• .claude/skills/ para as skills do projeto

A diferença importa: teste é assunto de projeto. Padrão de nome de arquivo e política de mock mudam de repositório pra repositório, então o lugar natural é .claude/skills/

Como descobrir o que escrever, se você ainda não sabe:

Se o padrão da casa já está na sua cabeça, pode ir direto: abra o SKILL.md e escreva as regras

Agora, se você não tem certeza de onde o modelo escorrega, a documentação de boas práticas recomenda começar por avaliação: rodar o agente em tarefas representativas, observar onde ele falha ou precisa de contexto extra, e construir a skill incrementalmente a partir dessas lacunas

É um diagnóstico rápido, não um pré-requisito eterno. Você roda uma vez, vê o que falta, e transforma cada lacuna numa linha de instrução. As lacunas SÃO o conteúdo da skill

O que não funciona é o contrário: sentar e escrever um documento lindo no vácuo, cheio de regra genérica que ninguém pediu

E se você quiser um apoio pra estruturar o arquivo, a Anthropic mantém o skill-creator, uma skill oficial que guia a criação de outras skills

Passo a passo: montando a skill de testes com contexto do projeto

Bora ver na prática?

1. Levante as regras do seu padrão de teste. Se você já sabe de cor o que o time exige (nome de arquivo, estilo de asserção, o que mockar), pule direto pro passo 2 e escreva isso. Se não sabe, pegue um arquivo do projeto que precise de teste de verdade, peça o teste sem nenhuma skill ativa e anote friamente: nome do arquivo saiu no padrão? A asserção está no estilo do time? Mockou o que devia? O erro comum deste passo é pedir uma tarefa de brinquedo: se você pedir teste pra uma função soma(), o Claude acerta e você não descobre lacuna nenhuma

2. Crie a pasta da skill e o SKILL.md. A estrutura é pasta + arquivo, nada além disso no começo

.claude/
└── skills/
    └── escrever-testes/
        └── SKILL.md

3. Escreva o frontmatter com os campos obrigatórios. O frontmatter exige name e description. O name tem no máximo 64 caracteres, aceita apenas letras minúsculas, números e hífens, e não pode conter palavras reservadas como anthropic ou claude. A description não pode ser vazia e tem no máximo 1024 caracteres

---
name: escrever-testes
description: ...
---

O erro comum deste passo é justamente o name: gente batiza a skill de claude-testes ou Testes_Unitarios por hábito, e aí o nome é inválido. Minúsculas, números e hífen, e sem claude no meio

4. Trate a description como GATILHO, não como enfeite. Ela é o que faz a skill ser acionada, então precisa dizer o que a skill faz E quando usar. Description vaga faz o agente simplesmente nunca acionar a skill

---
name: escrever-testes
description: Escreve, corrige e completa testes seguindo o padrão deste repositório (nome de arquivo, estilo de asserção, política de mock e fixtures). Use sempre que o pedido envolver criar teste novo, ajustar teste existente ou cobrir um caso que faltou.
---

Compare com o clássico "description: skill de testes". Essa segunda não diz QUANDO usar, e é por isso que ela nunca dispara sozinha

5. Preencha o corpo com o contexto que você levantou. Aqui mora o valor todo. As cinco informações que mais mudam a saída:

• padrão de nomes: onde o arquivo de teste nasce e com qual sufixo
• estilo de asserção: qual biblioteca, qual formato, o que o time não usa
• política de mock: o que mockar sempre, o que NUNCA mockar
• formato de fixture: se existe fixture compartilhada e de onde ela vem
• definição de teste pronto: o que precisa estar coberto pra você aceitar o PR

E tem um truque que muda tudo: prefira apontar arquivos de teste REAIS do repositório a escrever descrição abstrata

## Padrão de nomes
Arquivo de teste fica ao lado do código, mesmo nome + sufixo de teste

## Política de mock
Mockar: chamadas HTTP externas e relógio
Não mockar: repositórios internos e funções puras do próprio módulo

## Referência viva
Use `src/checkout/checkout.test.ts` como modelo de estrutura e de estilo de asserção
Use `tests/fixtures/pedido.ts` como modelo de fixture

O erro comum deste passo é escrever "siga as boas práticas de teste do projeto". Isso não é contexto, é desejo. Boas práticas do SEU projeto o modelo não conhece

6. Segure o tamanho do corpo. A documentação recomenda manter o corpo do SKILL.md abaixo de 500 linhas e dividir o excedente em arquivos separados. O padrão documentado é o da skill de PDF, cujo SKILL.md aponta para reference.md e forms.md, lidos só quando necessários

E por que isso importa? Por causa do progressive disclosure (carregamento em camadas): name e description ficam SEMPRE no contexto do agente, enquanto o corpo do SKILL.md e os arquivos de apoio só são lidos quando a tarefa combina com a description ou quando as instruções mandam abrir o arquivo

Ou seja: você pode ter uma referência gigante de casos de teste sem pagar contexto por ela o tempo todo

.claude/skills/escrever-testes/
├── SKILL.md
├── asercoes.md
└── fixtures.md

7. Separe o que é persistente do que é da tarefa. Nem toda instrução de teste pertence à skill. O CLAUDE.md dá instruções persistentes de projeto e é lido pelo Claude Code no início de cada sessão, e o comando /memory lista os arquivos de memória (CLAUDE.md, CLAUDE.local.md) nos escopos de usuário e projeto

Tome cuidado com o tamanho aqui: a documentação avisa que arquivos com mais de 200 linhas consomem mais contexto e podem reduzir a aderência às instruções, e que acima de 4 MiB o arquivo de memória é ignorado

Se a instrução só faz sentido em alguns arquivos, existem as path-scoped rules (regras com escopo por caminho), que carregam instruções apenas quando o Claude trabalha em arquivos que combinam com o padrão

8. Ajuste o acionamento. Por padrão os dois lados podem acionar a skill: você digitando /escrever-testes e o próprio Claude carregando automaticamente quando a conversa combina com a description

Se você quer a skill SÓ na mão, o campo disable-model-invocation: true restringe o acionamento à invocação manual

E tem o allowed-tools, que lista no frontmatter quais ferramentas ficam pré-aprovadas com a skill ativa. Atenção nesse: ele é suportado no Claude Code CLI e não se aplica a skills usadas via SDK

---
name: escrever-testes
description: ...
disable-model-invocation: true
---

O erro comum deste passo é ligar o disable-model-invocation: true "pra ter controle", esquecer disso, e depois passar a tarde achando que a skill quebrou porque ela nunca aparece sozinha

9. Confira numa tarefa de teste real, agora com a skill ativa. Peça o teste e olhe a primeira saída: nome de arquivo, estilo de asserção e mock já vieram no padrão da casa? Se sim, ótimo, para por aqui. Se ainda tem uma regra sendo ignorada, essa vira a próxima linha do SKILL.md, e não um parágrafo genérico novo

Incremental é isso: cada linha que entra existe porque uma regra real pediu por ela

A skill de testes não funciona como esperado: causas comuns

Sintoma: a skill nunca é acionada sozinha

Causa provável: a description descreve o que a skill faz mas não diz QUANDO usar, ou o disable-model-invocation: true está ativo no frontmatter

Solução: reescreva a description com o gatilho explícito ("use quando o pedido envolver criar ou corrigir teste") ou chame na mão com /nome-da-skill. Como prevenir: leia sua description imaginando que ela é a ÚNICA coisa que o agente vê da skill, porque é mais ou menos isso mesmo

Sintoma: o SKILL.md virou um documentão e a saída piorou

Causa provável: o corpo passou das 500 linhas recomendadas e a instrução importante ficou soterrada

Solução: divida em arquivos de apoio referenciados a partir do SKILL.md, no mesmo padrão da skill de PDF que aponta pra reference.md e forms.md. Como prevenir: sempre que for adicionar uma seção nova longa, pergunte se ela precisa estar sempre no corpo ou se pode ser carregada sob demanda

Sintoma: a instrução de teste é seguida no começo e ignorada no meio da sessão

Causa provável: arquivo de memória inflado (acima de 200 linhas a aderência às instruções cai)

Solução: enxugue o CLAUDE.md, deixe lá só o que vale pra sessão inteira e mova o resto pra skill ou pra path-scoped rules. Como prevenir: rode /memory de vez em quando e olhe o tamanho do que está sendo carregado

Sintoma: o teste gerado continua genérico mesmo com a skill ativa

Causa provável: o contexto foi escrito em termos abstratos ("use asserções claras", "mocke o necessário")

Solução: aponte arquivos de teste reais do repositório como referência e diga explicitamente o que NÃO copiar. Como prevenir: toda regra de estilo que você escrever deve ter um endereço junto, um caminho de arquivo que serve de modelo

Como o contexto muda a saída em projetos diferentes

Não existe uma skill de testes universal, e é aqui que fica claro o porquê. A informação que pesa muda conforme o projeto

A mesma lógica aparece em outras skills de padrão: em regras de breakpoint que o modelo segue o problema também é transformar convenção implícita em instrução concreta

Front com componentes:

O que mais dói aqui é nome de arquivo e fronteira do mock

A skill precisa saber onde o teste do componente nasce (pasta espelhada ou ao lado do componente), o que deve ser renderizado DE VERDADE e o que pode ser substituído por mock. Sem isso o Claude tende a mockar filhos que o time faz questão de renderizar, e o teste passa a testar o mock, não o componente

API de backend:

A pergunta número um é banco: o time roda teste contra banco real de teste ou mocka a camada de dados? Essa decisão sozinha muda todo o arquivo gerado

Depois vêm as fixtures compartilhadas (de onde saem, quem pode criar novas) e o formato das asserções de resposta: se o padrão é conferir status mais corpo inteiro, ou status mais campos específicos. O modelo chuta se você não disser

Base legada sem padrão claro:

Esse é o caso mais interessante, e o mais mal resolvido normalmente

A base tem dois estilos: o antigo, que ninguém quer mais, e o novo, que virou o padrão. Se a skill não sabe qual é qual, ela vai copiar o que encontrar primeiro, e tem MUITO mais arquivo antigo que novo por ali

Então a informação essencial vira: qual pasta é a referência boa, e qual estilo antigo não deve ser copiado mesmo estando espalhado pelo repositório. Escreva os dois, o que seguir e o que ignorar

Conclusão

Skill boa nasce de regra concreta apontada com endereço, não de documento escrito no vácuo

Com o contexto do projeto dentro do SKILL.md, o teste já nasce no padrão da casa, e não naquele formato genérico que serve pra qualquer repositório e pro seu nenhum

Seu próximo passo é bem concreto: escreva hoje as regras que você já sabe de cor (padrão de nome, estilo de asserção, política de mock) e aponte um arquivo de teste real do repositório como modelo. Se você não tiver certeza de alguma delas, a própria documentação recomenda o caminho: roda em tarefa real, vê onde falta contexto, e escreve a skill em cima disso

Aí você pede um teste com a skill ativa e confere a primeira saída. É a única medição honesta que existe aqui

Depois que o básico estiver funcionando, você expande: arquivo de apoio com os casos de asserção, outro com as fixtures, tudo carregado sob demanda pelo progressive disclosure

Começa pequeno, que funciona melhor… 😀

até o próximo post!