Como testar uma skill do Claude: evals, disparo e otimização da descrição

Uma skill que nunca dispara não é uma skill. É um arquivo.

Escrever uma skill do Claude é a parte fácil. Saber se ela funciona de verdade (se dispara quando você precisa e fica quieta quando não deve) exige evals.

Se você ainda não colocou uma skill em uso, comece pelo guia completo para construir skills no Claude Code. Para acertar a estrutura do SKILL.md antes de testar, leia o guia de estrutura e frontmatter do SKILL.md. Para exemplos reais de skills testadas, veja os exemplos de skills do Claude.

Skills tendem a disparar de menos, e você não percebe

A falha mais comum é o undertrigger: a skill existe, a descrição parece ok, e o Claude nunca a carrega. Você escreve uma query. Nada acontece. Você assume que funcionou. Não funcionou.

O Claude só busca uma skill quando decide que a tarefa não se resolve trivialmente com os próprios pesos. Uma descrição vaga ou passiva (“esta skill ajuda com X”) soa opcional. O Claude pula. A descrição é o único sinal que o Claude checa antes de decidir se carrega uma skill. Se ela não força a ação, nada carrega, e você nunca descobre: o modelo responde com confiança a partir dos dados de treino e segue em frente.

Monte o conjunto de evals antes de mexer na descrição

Monte umas 20 queries de eval antes de ajustar qualquer coisa. Metade deve ser de casos em que a skill deve disparar: queries reais dos casos de uso pretendidos. A outra metade deve ser de queries em que ela não deve disparar: temas vizinhos, intenção sobreposta, coisas que um usuário razoável perguntaria e que a skill nunca foi feita para tratar.

Divida em 60/40: doze para treino (o conjunto contra o qual você itera) e oito separadas para teste. Essa divisão importa. Se você otimiza só contra as queries de treino, vai dar overfitting. A descrição fica suspeitamente boa naqueles doze exemplos exatos e falha em qualquer coisa um pouco diferente. O conjunto de teste é a única medida honesta.

Rode cada query três vezes antes de registrar a nota. A decisão de disparo do Claude é probabilística. Uma única execução pode te dar um falso positivo ou um falso negativo. Três execuções por query te dão uma taxa confiável: 0/3, 1/3, 2/3, 3/3. A meta é taxa de disparo acima de 80% nas queries que devem disparar e abaixo de 20% nas que não devem. Qualquer coisa fora dessa faixa vale a pena corrigir.

O loop de evals

O orçamento é de cinco rodadas. Mais que isso e você normalmente está correndo atrás de ruído no conjunto de treino em vez de melhorar a skill. Cada rodada: proponha uma mudança na descrição, rode de novo as queries de treino três vezes cada, registre a taxa de disparo. Depois de cinco rodadas, escolha a descrição com a melhor nota no conjunto de teste, não no de treino. É essa que vai para produção.

Loop de eval da descrição

Entrada

~20 queries: mistura de deve-disparar e não-deve-disparar, divididas 60/40 entre treino e teste

↓

1. 01Rode o baseline

   Dispare cada query de treino 3× contra a descrição atual. Registre a taxa de disparo dos grupos deve-disparar e não-deve-disparar separadamente.

   ↓
2. 02Diagnostique a lacuna

   Undertrigger? Adicione frases de disparo explícitas e deixe a descrição um pouco insistente. Over-trigger? Aperte o escopo e adicione contexto de quando não usar.

   ↓
3. 03Proponha uma mudança

   Uma edição por rodada. Mudar várias coisas ao mesmo tempo torna impossível saber o que fez diferença.

   ↓
4. 04Rode o conjunto de treino de novo

   Rode todas as queries de treino de novo, 3× cada. Registre a nova taxa de disparo. Guarde todas as versões. Talvez você queira voltar.

   ↓
5. 05Repita até 5 rodadas e escolha pela nota de teste

   Depois de 5 rodadas (ou quando a taxa de treino estabilizar), pare. Avalie cada descrição candidata no conjunto de teste separado. A de melhor nota no teste vai para produção.

↓

Saída

Uma descrição que dispara de forma confiável em queries reais: verificado, não presumido

A regra de uma mudança por rodada é a disciplina que torna a iteração útil. Se você muda a descrição, adiciona uma frase de disparo e renomeia a skill na mesma passada, não dá para atribuir a variação na taxa de disparo a nenhuma decisão isolada. Trate a descrição como a variável e mantenha todo o resto fixo.

Três modos de falha, cada um com uma correção diferente

Depois de rodar esse loop em uma dúzia de skills em produção, os mesmos três padrões de falha continuam aparecendo. Eles vivem em partes diferentes da skill e pedem correções completamente diferentes. Confundir um com o outro desperdiça rodadas.

Modos de falha de disparo e de saída

Undertrigger e over-trigger são problemas de descrição. Drift de saída é problema de referência. Cada um pede uma alavanca diferente.

Modo de falha	Sintoma	Correção
Undertrigger	A skill existe, mas raramente dispara em queries relevantes	Adicione verbos de disparo explícitos; reescreva a descrição para ser um pouco insistente
Over-trigger	Dispara em queries vizinhas para as quais a skill não foi feita	Aperte o escopo; adicione exemplos de quando NÃO usar na descrição
Drift de saída	Dispara certo, mas ignora suas referências; responde pelos pesos	Adicione contraexemplos e anti-padrões aos arquivos de referência; reforce o mapa de carregamento

Undertrigger e over-trigger são os dois problemas de descrição. Rode o loop de evals acima. Drift de saída é problema de referência. A skill disparou. O modelo só escolheu não usar o que você construiu. Isso se corrige nos arquivos de referência e no mapa de carregamento, não na descrição.

Qualidade da saída: o teste que todo mundo pula

A taxa de disparo só diz se a skill disparou. Não diz nada sobre a resposta ter sido boa. Esse é outro teste, e a maioria das pessoas nunca roda.

O teste é simples: dê ao Claude a mesma entrada real duas vezes. Uma com a skill ativa, outra sem. Compare as duas respostas em cinco critérios.

Checklist de qualidade da saída

• ✓Obrigatório:
  Carregou o arquivo de referência certo.A resposta deve citar ou aplicar o framework ou os critérios de decisão específicos das suas referências, não um conselho genérico que o Claude daria sem elas.
• ✓Obrigatório:
  Aplicou o framework, não só a voz.Tom e vocabulário batendo com a skill é necessário, mas não suficiente. O framework (a Value Equation, o modelo RAISE, o seu checklist de decisão) deve estruturar a resposta, não só dar sabor a ela.
• ✓Obrigatório:
  Largou o "depende" genérico.Sem a skill, o Claude fica em cima do muro. Com ela, você deve ver julgamentos concretos. Se a resposta ainda soa como 'depende' sem nenhuma decisão, a skill não está ancorando a saída.
• ✓Obrigatório:
  É consistente em duas sessões separadas.Rode a mesma entrada numa sessão nova. A skill deve ancorar o mesmo método nas duas vezes. Variação grande entre sessões significa que as referências estão ralas demais ou o mapa de carregamento está ambíguo.
• ✓Obrigatório:
  A resposta falharia sem a skill.Essa é a régua de verdade. Se o Claude produz uma resposta tão boa só com os pesos, a skill não está agregando valor. A diferença entre com skill e sem skill deve ser óbvia.

Esse teste leva dez minutos, e a maioria pula porque exige rodar a mesma query duas vezes e comparar com cuidado. É o único jeito de saber se as suas referências destiladas estão chegando de fato à resposta ou paradas num diretório sem ninguém ler enquanto o Claude improvisa com os dados de treino.

Iterando a descrição: três movimentos concretos

Depois de rodar o eval de taxa de disparo, a maioria das descrições precisa de uma mudança estrutural: elas são passivas demais.

Compare estas duas descrições para a mesma skill:

Antes: “Esta skill ajuda com avaliação de ofertas usando os frameworks do Hormozi.”

Depois: “Use esta skill sempre que alguém pedir para avaliar, criticar, melhorar ou precificar uma oferta, value stack ou garantia. Antes de responder, carregue references/01-value-equation.md e references/11-decision-checklist.md.”

A primeira descrição diz ao Claude o que a skill é. A segunda diz quando usá-la e o que fazer primeiro. Essa diferença costuma levar a taxa de disparo de 40% para mais de 90% num conjunto de evals real.

Três movimentos que corrigem o undertrigger.

Nomeie os verbos de disparo explicitamente. Liste: “avaliar, criticar, revisar, melhorar, auditar, diagnosticar”. Se o verbo do usuário aparece na descrição, o Claude consegue casar direto. Não o faça adivinhar que “dá uma olhada na minha oferta” significa avaliar.

Adicione uma frase de quando usar. “Use esta skill sempre que…” é uma instrução, não um rótulo. A condicional deixa isso explícito.

Nomeie a primeira referência a carregar. Tornar o carregamento da referência obrigatório na descrição transforma uma opção num portão. O modelo não consegue responder de forma genérica se a descrição já disse qual arquivo abrir primeiro.

Para skills que disparam demais, vale o inverso. Adicione uma frase de quando NÃO usar: “Não use esta skill para escrita em geral, code review ou debugging técnico.” Esse limite vai se sustentar.

Quando a descrição está pronta

Uma descrição está pronta quando a taxa de disparo no conjunto de teste passa de 80/20, o checklist de qualidade da saída passa em duas entradas reais e duas sessões separadas produzem respostas consistentes para a mesma query. Versione. Faça commit da descrição no diretório da skill com uma nota do que mudou e por quê. Skills se degradam: sai uma versão nova do Claude, os padrões de uso mudam e a taxa de disparo cai. Você vai querer esse histórico quando precisar depurar isso daqui a seis meses.

Para ver como é por dentro um SKILL.md pronto para produção, o guia de estrutura e frontmatter do SKILL.md cobre os campos que afetam o disparo e o carregamento. Para exemplos concretos de skills que passaram por esse processo, veja os exemplos de skills do Claude.

Evals fecham a distância entre entregue e confiável

Construir uma skill leva uma tarde. Saber que ela funciona é outra história. Isso não aparece na contagem de arquivos, mas aparece em a skill ser usada de fato ou não.

Vinte queries de eval. Uma divisão 60/40 entre treino e teste. Três execuções por query. Até cinco rodadas de edição da descrição. Escolha a vencedora pela nota no conjunto de teste. Depois rode o checklist de qualidade da saída para confirmar que suas referências estão chegando à resposta, e não só paradas num diretório.

Esse é o protocolo completo. Nada glamouroso, mas é a diferença entre uma skill que você colocou no ar e uma skill em que você confia.

Se você ainda não escreveu sua primeira skill, o guia para construir skills no Claude Code é o ponto de partida certo.

Como sei se a minha skill está disparando de verdade?+

Rode a mesma query três vezes e veja se a resposta aplica o framework da skill. Se a resposta é genérica (nenhum framework específico, nenhum sinal de referência carregada, nenhuma diferença relevante do que o Claude produziria sem a skill), provavelmente ela não disparou.

O teste mais limpo é a comparação com/sem: rode a query uma vez com a skill presente e outra com o SKILL.md removido temporariamente. Se as respostas são idênticas, o disparo não é o seu problema. A qualidade da saída é.

Por que rodar cada query de eval três vezes em vez de uma?+

A decisão de disparo do Claude é probabilística. Uma única execução pode te dar um falso positivo (a skill dispara numa query em que normalmente não dispararia) ou um falso negativo (é pulada numa query que deveria pegar). Três execuções por query te dão uma taxa: 0/3, 1/3, 2/3, 3/3. Estável o suficiente para tomar uma decisão.

Por que escolher a melhor descrição pelo conjunto de teste e não pelo de treino?+

Porque dá para sobreajustar uma descrição às queries de treino. Depois de cinco rodadas de iteração, uma descrição pode ficar muito boa exatamente nos doze exemplos que você testou e falhar em qualquer coisa um pouco diferente.

O conjunto de teste (as oito queries que você separou e contra as quais nunca iterou) é a única medida honesta de generalização. Se você olhar para ele antes de parar de iterar, ele deixa de ser teste.

Qual a diferença entre undertrigger e drift de saída?+

Undertrigger significa que a skill não dispara. Drift de saída significa que ela dispara, mas a resposta ainda ignora suas referências e puxa dos pesos de treino do modelo.

Os dois produzem respostas medíocres, mas as correções são completamente diferentes. Undertrigger é problema de descrição: itere o loop de evals. Drift de saída é problema de referência e de mapa de carregamento. A descrição já está fazendo o trabalho dela.

Preciso mesmo de 20 queries de eval, ou dá para usar menos?+

Para uma skill estreita e bem definida (que trata um único tipo de documento ou uma decisão específica), 15 costumam bastar. Menos que isso e o sinal fica ruidoso demais para iterar com confiança.

A divisão 60/40 importa mais que o número absoluto. Você precisa de exemplos de treino suficientes para iterar e de exemplos separados suficientes para avaliar de forma justa. Não junte tudo num conjunto só.

Uma descrição melhor sempre conserta uma skill que não está funcionando?+

Não. A descrição controla o disparo. Se a skill dispara, mas a saída continua genérica, o problema está nas referências ou no mapa de carregamento, não na descrição.

Rode sempre o checklist de qualidade da saída antes de gastar rodadas de eval em edições da descrição. Se a resposta com skill já é bem diferente da resposta sem skill, o seu mecanismo de disparo está ok e você está resolvendo o problema errado.