Uma skill pode parecer boa porque tem muitas instruções. Pode até funcionar em uma demonstração. Isso não responde à pergunta mais importante: ela ajuda o agente a tomar o mesmo caminho certo quando o pedido muda um pouco?
Foi para tratar essa diferença que criei a skill-evaluation. Ela não mede se a resposta final de uma skill é bonita nem tenta certificar uma solução. O foco é outro: revisar a construção da skill, seus gatilhos, sua estrutura e a forma como ela direciona o agente.
Esse trabalho faz parte do ecossistema de Agent Skills que mantenho no repositório aberto e no skilldev.pro. A base é simples: arquivos SKILL.md pequenos o suficiente para serem carregados sob demanda, mas específicos o bastante para orientar uma tarefa real.
O problema não é só ter uma skill ruim
Uma skill fraca costuma falhar de maneiras discretas. Ela é chamada fora de contexto. Esconde uma regra essencial em uma referência que ninguém abre. Dá instruções genéricas, que soam corretas mas não mudam o comportamento do agente. Ou acumula parágrafos que ninguém mais sabe por que existem.
O resultado pode ser ainda mais traiçoeiro que um erro explícito: o agente parece obedecer, mas improvisa em pontos críticos. A avaliação tenta tornar esses riscos visíveis antes que a skill vire uma dependência difícil de revisar.
Quatro eixos para olhar a skill de frente
O avaliador organiza 18 critérios em quatro eixos. Quatorze valem para toda skill; quatro só entram quando fazem sentido para a categoria, como scripts, memória, setup ou hooks.
| Eixo | Pergunta central |
|---|---|
| Trigger | A skill é invocada no momento certo e sua descrição ajuda o agente a encontrá-la? |
| Structure | Os passos, referências e ponteiros estão organizados para cada caminho de uso? |
| Steering | As instruções dão direção concreta, critérios de conclusão e alertas sobre armadilhas? |
| Pruning | Há duplicação, conteúdo obsoleto, excesso ou frases que não mudam o comportamento do agente? |
Não é uma lista para marcar no automático. Cada critério precisa de evidência em arquivo, seção ou linha. Se não houver evidência, o próprio método pede que a nota não seja atribuída. É a regra de cite-or-cut: ou existe base para o achado, ou ele sai do relatório.
O fluxo também inclui um teste de trigger para skills invocadas pelo modelo. São cinco pedidos que deveriam acionar a skill e cinco que não deveriam. A ideia é observar duas coisas diferentes: a taxa de acerto quando ela é necessária e o vazamento quando ela aparece onde não deveria.
O que uma nota C ensina
Na escala do avaliador, C cobre de 40 a 59 pontos: uma skill funcional, mas com lacunas significativas. Não é um veredito de descarte. É um sinal de que há trabalho concreto a fazer antes de tratá-la como referência.
O caminho útil depois de uma nota assim não é reescrever tudo. Começa pelos achados que alteram o comportamento: um gatilho ambíguo, uma conclusão sem critério verificável, uma instrução enterrada ou uma regra duplicada. Corrige-se o ponto, roda-se a avaliação de novo e compara-se o resultado.
[DADO OU EXEMPLO REAL NECESSÁRIO: qual skill recebeu Grade C, quais critérios puxaram a nota e qual foi o score obtido na avaliação publicada em 2026-07-03.]
Tip
Uma nota baixa fica mais útil quando vem acompanhada de evidência e de uma ação priorizada. O objetivo não é colecionar grades; é encurtar o caminho entre um achado e uma melhoria verificável.
Como usar
Instale a skill a partir do repositório:
npx skills add https://github.com/fabricioctelles/skills -s skill-evaluationEm seguida, peça para avaliar uma pasta de skill ou o seu SKILL.md. O fluxo lê o material da skill, classifica sua categoria, pontua somente os critérios aplicáveis e produz um scorecard com evidências, modos de falha e ações priorizadas. Também aceita comparar duas skills lado a lado.
O cálculo da média ponderada fica em um script documentado. Depois de preencher as notas com base nas evidências, rode algo neste formato dentro do repositório de skills:
python skills/skill-evaluation/scripts/score.py \ 1:80:2 2:75:2 3:90:1 4:85:2 \ 15:NA:1 16:NA:1 17:70:1 18:NA:1NA retira um critério que não se aplica do cálculo. Para CI, o script também aceita --fail-below 60 e retorna erro quando a nota geral fica abaixo do limite.
Avaliar, corrigir, reavaliar
O avaliador entra antes dos testes funcionais e do monitoramento contínuo. Primeiro, pergunta se a skill está bem construída e se é acionada direito. Depois, os evals verificam se ela entrega o resultado esperado. Por fim, benchmarks acompanham regressões e utilidade ao longo do tempo.
É um ciclo simples, mas exige disciplina: avaliar, corrigir os achados prioritários, reavaliar e comparar. Skill boa não é a que parece completa. É a que deixa claro quando deve entrar em cena, o que precisa fazer e como sabemos que terminou.
