Como testar se a sua skill do Jev está sendo acionada na hora certa?

Fala aí, beleza? Skill escrita, SKILL.md no lugar, instalação feita… e ninguém sabe se aquilo dispara alguma vez na vida

Esse é o buraco mais comum de quem começa a mexer com skills: a gente trata o acionamento como mágica e só descobre que nada foi carregado quando o resultado sai igualzinho ao de antes

O que decide se a skill entra ou não é o campo description do frontmatter: é ele que o Claude compara com o pedido do usuário pra escolher acionar

E aqui entra a parte nova. Com o mod Jev Skill Suggestion, a listagem de skills sai do contexto e quem lê as descriptions e escolhe no máximo uma skill (ou nenhuma) passa a ser o Jev, o modelo System One da TypeSafe

Ou seja: muda quem julga, e muda o que você precisa testar

Bora montar o roteiro de verificação? 🙂

O que você precisa antes de testar

Antes de sair rodando prompt, três coisas precisam estar de pé

1. A skill existe onde o Claude Code procura. No Claude Code, skills pessoais ficam em ~/.claude/skills/ (valem em todos os projetos) e skills de projeto em .claude/skills/ (versionadas com o time). Cada skill é um diretório com um arquivo SKILL.md dentro

2. Versão do Claude Code compatível com os comandos do roteiro. O atalho /skills e os controles de visibilidade pedem Claude Code v2.1.280 ou superior. O /skill-doctor pede v2.1.252 ou superior. Se o comando não existir na sua instalação, é versão, não é bug da skill

3. O frontmatter parseia. Sem isso o resto é teatro. O comando claude plugin validate encontra os SKILL.md com frontmatter quebrado

Se o seu teste envolve o fluxo do Jev na frente do acionamento, aí entra o mod. Segundo a própria página do mod, ele é criado por Daniel Ávila (projeto claude-code-templates), e instala assim:

npx claude-code-templates@latest --mod productivity/jev-skill-suggestion

Curso Recomendado

Curso de Jev: Sistemas Mais Inteligentes, Rápidos e Robustos

Desenvolva sistemas mais inteligentes, rápidos e robustos com Jev

Conhecer curso

Depois roda o setup, que é o passo responsável por tirar a listagem de skills do contexto:

/jev-skill-suggestion:setup

Duas coisas pra deixar claras antes de você colocar isso num fluxo de produção

O Jev está em early access, conforme a própria TypeSafe

E a cobrança é por token de entrada: US$ 0,042 por 1 milhão de tokens de entrada no jev-1.12, com tokens de saída gratuitos. Como ele passa na frente de cada prompt, a conta é de entrada, não de geração

Roteiro de verificação passo a passo

A ideia aqui é separar as perguntas. "A skill dispara quando deveria?" é uma pergunta. "O que ela produz quando dispara é o que eu esperava?" é OUTRA. A própria documentação do Claude Code separa essas duas medições, e é aí que quase todo teste caseiro se perde

1. Valide o frontmatter primeiro

claude plugin validate ~/.claude/skills
claude plugin validate .claude/skills

O erro comum deste passo: passar uma tarde ajustando texto da description quando o YAML nem estava sendo parseado. Valide antes de teorizar

2. Confirme se a skill aparece (ou se ela NÃO deveria aparecer)

Digite /skills pra abrir o diálogo de skills e olhar o que está disponível na sessão

Aí vale entender dois campos do frontmatter que mexem em quem pode invocar:

• disable-model-invocation: true: só você invoca, o Claude não aciona sozinho
• user-invocable: false: só o Claude invoca, e a skill não aparece na listagem

O erro comum deste passo: caçar na listagem uma skill marcada com user-invocable: false e concluir que "não instalou". Ela está lá, só não se mostra

3. Escreva a lista de prompts positivos E negativos

Positivo é o pedido que DEVERIA acionar. Negativo é o pedido que NÃO deveria

O erro comum deste passo: escrever só os positivos. Sem os negativos você nunca descobre que sua skill está sendo carregada em todo "arruma esse arquivo aí" e comendo contexto de graça

4. Rode cada prompt em sessão NOVA, com e sem a skill

Esse é o método que a documentação do Claude Code recomenda: reunir prompts realistas e rodar cada um em uma sessão nova com a skill disponível e de novo com ela desativada, comparando os resultados

Por que sessão nova? Porque o contexto de quem acabou de escrever a skill mascara falhas das instruções. Você já explicou tudo no chat, o modelo acerta, e você acha que foi a skill

O erro comum deste passo: testar na mesma sessão em que você escreveu a skill. É o clássico, já me ferrei com isso

5. Force a execução pra isolar o problema

Enviar /<nome> roda uma skill user-invocable mesmo quando ela não aparece na listagem. Na skill oficial da TypeSafe, por exemplo, a chamada manual é:

/typesafe:typesafe-ai

Se forçado funciona e automático não, o problema é de ACIONAMENTO, ou seja, é description. Se forçado também sai errado, o problema é de CONTEÚDO, é o corpo do SKILL.md

O erro comum deste passo: ver a skill disparar e comemorar. Disparou não é sinônimo de acertou

6. Olhe o diagnóstico de uso e custo

/skill-doctor

Ele mostra quanto cada skill custa e com que frequência é usada, sinaliza skills da listagem que nunca foram invocadas e indica onde desligá-las. Em sessão interativa o relatório abre na aba Stats do gerenciador /plugin

Skill que nunca foi invocada é sintoma direto de description ruim, ou de skill que não deveria estar ali ocupando espaço

7. Automatize a lista que você acabou de montar

Se a skill está empacotada em plugin, o claude plugin eval roda cada prompt em sessão isolada com e sem o plugin e pontua com graders definidos por você ou escritos por ele mesmo. Pra iterar dentro da conversa existe o plugin skill-creator, com formato evals/evals.json

O erro comum deste passo: deixar a automação pro "depois". Depois é quando você mexe na description, quebra três casos e não tem base de comparação

Prompts que deveriam acionar e prompts que não deveriam

Vamos sair do abstrato. Pega a skill oficial da TypeSafe: ela vive no repositório typesafe-ai/skills, no arquivo skills/typesafe-ai/SKILL.md, e serve pra dar ao agente contexto sobre a API da TypeSafe: os três tipos de pergunta, padrões de arquitetura e boas práticas

Instalação no Claude Code:

claude plugin marketplace add typesafe-ai/skills
claude plugin install typesafe@typesafe-ai

Fora do Claude Code, em outros agentes:

npx skills add typesafe-ai/skills --skill typesafe-ai

Com isso na mão, a lista de positivos sai quase sozinha, porque as perguntas enviadas ao Jev são de três tipos: Choice (escolher uma opção de um conjunto fechado, com probabilidade por opção), Score (nota em níveis ordenados) e Noul (pergunta sim/não, que retorna a probabilidade de sim)

Prompts que DEVERIAM acionar:

• "classifica esse ticket em uma de quatro categorias e me devolve a probabilidade de cada opção"
• "quero dar uma nota de 1 a 5 pra qualidade dessa resposta, em níveis ordenados"
• "preciso de um sim ou não com probabilidade pra saber se esse comentário é spam"
• "como eu estruturo essa etapa de decisão do meu agente sem depender de texto gerado?"

Repara no padrão: o pedido carrega o vocabulário da tarefa (escolha fechada, nota, sim/não, decisão tipada), que é exatamente o que a description tem que prever

Prompts que NÃO deveriam acionar:

• "refatora essa função pra ficar mais legível"
• "instala o eslint nesse projeto"
• "escreve um README pro repo"
• "traduz esse texto pro inglês"

Esses são os seus negativos. Se a skill entra em "escreve um README", você tem um falso positivo, e o custo dele não é zero: o conteúdo completo da skill entra no contexto sem motivo

Como isolar um falso positivo? Roda o negativo em sessão nova, com a skill disponível, e depois roda o MESMO prompt com a skill fora. Se o comportamento muda, ela acionou. Se muda pouco mas o consumo cresce, ela acionou e não fez nada de útil

E se o seu problema é o outro lado da moeda, ou seja, validar a lógica que consome a resposta, dá pra testar o código que chama o Jev com mocks e casos de borda, sem gastar requisição

Quando o comportamento não bate: o que ajustar na description

Primeiro, o conceito que explica quase todos os sintomas

As descrições das skills entram no contexto no início da sessão. O conteúdo completo do SKILL.md só é carregado quando a skill é usada

Ou seja: no momento da decisão, o modelo não leu a sua skill. Ele leu UMA frase sobre ela. Se a decisão está errada, é nessa frase que você mexe, não nas 900 linhas de instrução lá dentro

A boa prática oficial de escrita é bem direta: a description precisa dizer o que a skill faz E quando usá-la, sempre em terceira pessoa, porque ela é injetada no system prompt

O exemplo que a própria documentação dá:

"Extract text and tables from PDF files, fill forms, merge documents.
Use when working with PDF files or when the user mentions PDFs, forms,
or document extraction."

Se liga na segunda frase: ela lista os gatilhos. "Use when… or when the user mentions…"

É isso que falta nas descriptions das skills que não disparam. A pessoa descreve a skill pra outro dev, não pro modelo que vai comparar aquilo com "me ajuda com esse PDF aqui"

Como prevenir? Sempre que você tocar na description, roda a lista de positivos e negativos de novo. Mudança de uma palavra ali muda comportamento, e não existe jeito de adivinhar qual

Como o Jev muda a conta do acionamento

Agora a parte interessante pra quem está entrando no fluxo com o Jev

O mod Jev Skill Suggestion retira a listagem de skills do contexto e coloca o Jev na frente de cada prompt: ele escolhe no máximo uma skill (ou nenhuma) a partir das descriptions, e só o SKILL.md dessa skill chega ao contexto

O desenho vem do cookbook oficial de skill suggestion da TypeSafe, que escolhe no máximo uma skill por turno entre as 182 do catálogo Hermes da Nous Research. São duas requisições: uma ranqueia todas as skills e pergunta se o turno precisa de alguma, e a segunda lê as três primeiras em detalhe e pode rejeitar todas. Média abaixo de 0,30 não sugere nada

A medição do cookbook é sobre 488 requisições contra o claude-haiku-4-5-20251001, com as skills do catálogo Hermes, e o resultado é que as duas requisições por turno (ranquear + verificar) reduzem os carregamentos errados de skill em mais da metade

A página do mod Jev Skill Suggestion, citando esse cookbook sobre o catálogo de 182 skills, coloca números nisso: carregamentos errados caindo de 16,8% para 7,3% e os desnecessários de 9,8% para 4,0%

Esses percentuais aparecem na página do mod, não na leitura direta do cookbook, então trate como o que são: a métrica que quem empacotou a solução divulga

Agora a consequência prática pro seu teste, que é o que importa aqui

Nesse fluxo, a description deixa de ser "uma dica" e passa a ser praticamente o ÚNICO material que decide. Não tem mais o contexto da conversa inteira ajudando o modelo a inferir que aquela skill fazia sentido

Um julgador dedicado lê sua frase e decide

Frase ruim, acionamento ruim. Testar a description vale ainda mais depois do mod, não menos

O que aconteceu quando rodamos o mesmo projeto com e sem a skill

Esse método de "roda com, roda sem" não é teoria pra mim, eu usei ele num teste gravado

No vídeo eu instalei uma skill de design frontend num projeto e, antes de qualquer coisa, rodei a listagem pra confirmar que ela aparecia disponível. Apareceram duas versões dela ali, e eu escolhi de propósito a mais recente, deixando a antiga de lado

Pra testar o acionamento, abri dois terminais com o MESMO prompt

Num deles eu reforcei explicitamente: "não utilize skills de design, use somente os conhecimentos do Claude". A ideia era garantir que nenhuma skill entrasse sem eu querer

No outro, mandei direto: "use a skill de design frontend"

O primeiro sinal de que a skill estava sendo processada de verdade foi o tempo. O projeto com skill demorou visivelmente mais pra começar a cuspir arquivos, e eu atribuo isso ao óbvio: a IA precisa ler todo o conteúdo da skill antes de agir, e isso consome contexto

Depois eu comparei as duas landing pages seção por seção: header, hero, prova social, features, depoimentos, pricing, CTA e footer

A versão com a skill gerou um logo próprio e eliminou os travessões do texto, coisa que eu associo às regras anti padrão de IA que a skill carrega. Em depoimentos e footer, sinceramente, a diferença foi pequena

No fim eu percebi uma melhora de 10 a 15%, e isso é subjetivo, é feeling meu olhando os dois resultados

Moral da história, e é por isso que esse relato está aqui: a skill disparou, dá pra provar que disparou (o tempo dobrou, o resultado mudou de cara), e mesmo assim o ganho foi sutil

Disparar não é o mesmo que melhorar

Pra quem não tem domínio de design, acho que vale testar como ganho rápido. Pra quem já manja de prompt e de design, dá pra chegar em resultado igual ou melhor sem ela, gastando menos tokens

E é exatamente o "com e sem" que revela esse trade-off. Sem o terminal de controle, você nunca saberia que pagou o dobro de tempo por 1 ponto de nota

Próximo passo

Recapitulando o roteiro, que é curto quando você vê junto

Valide o frontmatter, confira a listagem, escreva positivos e negativos, rode cada prompt em sessão nova com e sem a skill, force com /<nome> pra separar acionamento de conteúdo, olhe o /skill-doctor e depois automatize a lista em evals

Duas coisas pra levar daqui

Primeira: salve a lista de prompts positivos e negativos JUNTO da skill, no mesmo diretório. Ela é parte do projeto, não é rascunho

Segunda: repita o roteiro sempre que você mexer na description. Sempre. É a linha mais sensível do arquivo, e no fluxo com o Jev ela é praticamente a única coisa que decide se a skill entra

Se você quer um começo de dez minutos hoje, roda claude plugin validate nas suas skills e abre o /skill-doctor pra ver quais nunca foram invocadas

Aposto que tem pelo menos uma dormindo ali de graça… 😀

Até o próximo post!