Como testar uma skill nova no Claude Code antes de confiar nela no dia a dia

Instalar skill virou coisa de dois minutos

Aí você acumula cinco, dez, um marketplace inteiro, e num belo dia percebe que não faz a menor ideia se ALGUMA delas melhorou alguma coisa de verdade

O problema nem é a skill ser ruim, é o teste ser ruim

Quase toda skill parece funcionar logo depois que você escreveu ela: o contexto da sessão está cheio, você explicou o que queria, corrigiu o Claude duas vezes, colou exemplo… a tarefa sai redondinha e o crédito vai pro SKILL.md, quando quem fez o trabalho foi a conversa

A saída é velha como laboratório de escola: mesma tarefa, duas rodadas, uma sem a skill e outra com ela, resultado comparado lado a lado

Bora montar esse protocolo?

O que você precisa antes de testar a skill

Primeiro, saber onde a coisa mora…

Skills personalizadas no Claude Code são baseadas em arquivo no disco, sem upload por API

São duas pastas, conforme o escopo:

• ~/.claude/skills/ para skill pessoal, que vale em todos os projetos
• .claude/skills/ para skill do projeto atual

Cada skill é uma pasta que contém um SKILL.md: frontmatter YAML de metadados mais o conteúdo em markdown

~/.claude/skills/
  summarize-changes/
    SKILL.md

E aqui tem um detalhe que muda TODO o teste: o campo description é o texto que o Claude compara com o pedido do usuário pra decidir se aciona a skill

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

Por isso ele precisa dizer duas coisas, o que a skill faz E quando usar

---
name: summarize-changes
description: Resume as mudanças do diff atual. Use quando o usuário pedir um panorama do que mudou no repositório
---

Se você ainda não tem repertório pra calibrar isso, vale ler o SKILL.md de skills do Claude prontas e ver como gente experiente escreve a description

Com a casa arrumada, defina três coisas antes de rodar qualquer comando:

• uma tarefa-piloto REAL, dessas que você faz toda semana
• que seja repetível: mesmo repositório, mesmo estado, mesmo prompt
• e o critério de sucesso escrito ANTES da primeira rodada

Esse último item é o que separa teste de torcida =)

Protocolo da tarefa-piloto: rodando a mesma tarefa com e sem a skill

1. Escreva a tarefa e as asserções

Asserção é um item objetivo que precisa aparecer na saída pra valer aprovado, tipo "listou os arquivos alterados", "agrupou por módulo", "não inventou nome de arquivo"

Se você não consegue marcar aprovado ou reprovado olhando a saída, a asserção está vaga demais

O erro comum deste passo: escrever asserção do tipo "a resposta tem que ser boa", que qualquer texto cumpre

2. Zere o contexto com /clear

/clear

O /clear reseta a conversa pra contexto vazio, então os próximos prompts começam sem histórico

E não, você não perde nada: a conversa antiga continua em disco e pode ser retomada pelo ID da sessão

Sessão limpa importa porque o contexto que sobrou da criação da skill mascara falhas nas instruções escritas, e é justamente a instrução escrita que você quer testar

O erro comum deste passo: testar na mesma sessão em que a skill foi criada

3. Rode a rodada de controle, SEM a skill

/skills

O /skills abre a lista de skills disponíveis dentro da sessão interativa e permite mudar o estado de cada pacote:

Pra rodada de controle, desligue o pacote da skill em teste e mande a tarefa-piloto exatamente como você escreveu

Guarde a saída inteira, ela é sua linha de base

O erro comum deste passo: ajustar o prompt "só um pouquinho" porque a resposta veio fraca, e aí a comparação morre ali

4. /clear de novo e rode a mesma tarefa com a skill ligada

Mesmo prompt, mesmo repositório, mesmo estado

Agora observe três coisas: se o Claude encontra a informação certa, se aplica as regras da skill e se conclui a tarefa

O erro comum deste passo: emendar a segunda rodada na primeira sessão, com a saída de controle ainda na tela influenciando tudo

5. Compare as duas saídas contra as asserções, não contra a impressão

Monte uma tabelinha e marque na régua que você escreveu no passo 1:

Se as duas colunas empatam, a skill não provou nada ainda, e tudo bem: isso é informação, não fracasso

O erro comum deste passo: concluir que a skill funciona porque a resposta veio bonita e bem formatada 😀

Como forçar o acionamento e isolar o que está sendo testado

Tem uma armadilha clássica aqui: você testa a skill, ela não muda nada, e você culpa a instrução… quando na real ela nem foi acionada

São dois testes diferentes morando no mesmo experimento, o do acionamento e o da instrução

Dá pra separar:

1. Force a invocação manual com disable-model-invocation

---
name: summarize-changes
description: Resume as mudanças do diff atual. Use quando o usuário pedir um panorama do que mudou no repositório
disable-model-invocation: true
---

Com disable-model-invocation: true, só o usuário pode invocar a skill, via /nome-da-skill, e o Claude não aciona automaticamente

Assim você garante que a skill entrou em cena e testa APENAS a qualidade da instrução

Depois, se quiser, tire o campo e teste o acionamento automático separado, que é onde a description está sendo julgada

O erro comum deste passo: misturar os dois testes e não saber qual dos dois falhou

2. Limite o campo de ação com allowed-tools

O campo allowed-tools no frontmatter define a lista de ferramentas que o Claude pode usar enquanto a skill está ativa, incluindo padrões de Bash e nomes de ferramentas MCP

Pra teste isso é ótimo: menos variável solta, menos caminho alternativo pro Claude chegar no resultado sem seguir a skill

E guarda esse campo na cabeça, porque ele volta lá embaixo quando o assunto for skill que veio de estranho

3. Cheque quanto da sua skill chega no modelo com /context

/context

A linha Skills do /context reporta o tamanho da listagem de skills já depois de aplicado o orçamento de contexto, ou seja, exatamente o que o modelo recebe

4. Veja quem está pagando a conta com /doctor

/doctor

O /doctor dá uma estimativa do custo de contexto da listagem de skills e aponta os maiores contribuintes

E por que isso muda o teste?

Porque quando a listagem estoura o orçamento, o Claude Code encurta descrições, e ele começa a cortar pelas skills que você MENOS usa, enquanto as mais usadas mantêm o texto completo

Adivinha em que categoria está a skill nova que você acabou de instalar 🙂

Ou seja: a description pode nem estar chegando inteira no modelo, e aí o problema não é a instrução, é a listagem

Dá pra mexer nisso com a configuração skillListingBudgetFraction, que aumenta a fatia da janela de contexto reservada à listagem, ou com a variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET, que fixa um número de caracteres

O erro comum aqui: reescrever o corpo da skill três vezes quando o buraco era description cortada, ou description que não diz QUANDO usar

Automatizando o teste com o skill-creator

Fazer isso na mão uma vez, beleza

Fazer pra dez skills, com três asserções cada, aí já vira serviço…

Pra isso existe o skill-creator, plugin oficial da Anthropic publicado no repositório anthropics/claude-plugins-official, feito pra criar skills e melhorá-las de forma iterativa

1. Instale pelo marketplace oficial, dentro do Claude Code

/plugin install skill-creator@claude-plugins-official

2. Peça a avaliação da skill que você quer testar

Basta pedir em texto normal, algo como:

avalie minha skill summarize-changes com o skill-creator

3. Leia o que ele produz, que é o mesmo protocolo lá de cima em escala

Ele roda os casos de teste isolados, um subagente por caso, cada um com contexto limpo, registrando contagem de tokens e duração

A etapa de grading checa cada asserção contra a saída e grava pass ou fail com evidência em grading.json, então você consegue auditar POR QUE algo passou

E o benchmark agrega taxa de acerto, tempo e tokens comparando a execução com a skill contra a execução sem a skill

Repara que é literalmente a tarefa-piloto: duas rodadas, mesma tarefa, comparação lado a lado, só que automatizada e repetível 🙂

O erro comum deste passo: rodar o benchmark com asserção vaga, que aprova qualquer saída, e sair achando que tem prova quando tem só um relatório bonito

Quando vale rodar o teste (e quando é obrigatório)

Nem toda skill merece protocolo completo, mas tem quatro situações em que eu não pularia:

Skill que você acabou de escrever

É o caso mais óbvio e o mais ignorado

O teste em sessão limpa é a única prova de que a instrução se sustenta sozinha, sem a conversa em que ela nasceu segurando a mão dela

Pilha grande de skills instaladas

Aqui o /context e o /doctor são os melhores amigos: eles mostram o tamanho da listagem depois do orçamento e quem são os maiores contribuintes

Skill que custa contexto e não passa no teste é peso morto

Skill que veio de terceiros

Nesse caso a inspeção ANTES de rodar deixa de ser boa prática e vira obrigação

Aqui o allowed-tools troca de papel: lá em cima ele era ferramenta de teste, aqui ele é a lista do que aquela pasta de estranho pode fazer na sua máquina enquanto estiver ativa

São três mecanismos pelos quais uma skill de terceiros age no seu ambiente, e os três merecem leitura antes de dar play:

• a lista allowed-tools no frontmatter, que diz quais ferramentas ficam liberadas
• o diretório scripts/ dentro da pasta da skill, que é código pronto pra rodar
• a injeção dinâmica de contexto, que é conteúdo entrando na conversa sem você digitar

Vale olhar com calma o que você realmente baixa antes de dar play em pasta de estranho

Skill distribuída como plugin

O /plugin gerencia marketplaces e instalação, e plugins podem trazer uma pasta skills/ junto

Ou seja: você instalou "um plugin", mas entraram skills no seu ambiente, e elas entram na conta da listagem igual às suas

Um detalhe que explica muita coisa: o Claude Code segue o padrão aberto Agent Skills, que funciona em várias ferramentas de IA, e acrescenta extensões próprias como controle de invocação, execução em subagente e injeção dinâmica de contexto

Por isso parte do comportamento só aparece testando DENTRO dele, e não adianta confiar em como a skill se comportou em outra ferramenta

Conclusão

Confiança em skill se mede por comparação, não por impressão

A resposta bonita é a pior evidência que existe, porque ela aparece com skill, sem skill e até com a skill quebrada

Próximo passo prático, hoje mesmo: escolhe UMA skill já instalada, escreve três asserções, roda a tarefa duas vezes com /clear entre as rodadas e marca aprovado ou reprovado item por item

Se as duas colunas empatarem, antes de culpar o corpo da skill, revise a description e cheque no /context se ela está chegando inteira no modelo

E quando esse ritual manual começar a cansar, plugue o skill-creator e transforme ele em benchmark repetível, com grading e comparação de tokens e tempo

até o próximo post! 😀