Uma skill extraída de uma conversa bem-sucedida pode carregar instruções que só servem para aquela tarefa. Para avaliar agent skills, prepare casos novos e compare o mesmo agente com e sem a skill. Você precisa de uma sessão com a tarefa resolvida, acesso às instruções dela e um ambiente onde possa executar cada teste com contexto limpo.
O objetivo é verificar que parte do procedimento se transfere: como ele interpreta a entrada, quais decisões toma e como verifica a saída. Repetir o trabalho original serve para revisar a extração, mas são as tarefas reservadas que colocam a reutilização à prova.
O que você precisa para avaliar uma skill
Uma Agent Skill é uma pasta com um arquivo SKILL.md, que combina metadados YAML e instruções Markdown. Ela também pode incluir scripts, referências e recursos. Segundo a especificação oficial, os campos obrigatórios são name e description; o nome deve ser igual ao da pasta.
Prepare também o acesso ao modelo e às ferramentas com que você vai executar os testes. Você precisa conseguir separar as sessões e salvar as saídas, porque uma resposta correta sem seu contexto de execução oferece pouca informação para comparar.
Defina desde o início o que você quer melhorar. Uma skill que ensina uma capacidade é avaliada pelo que consegue resolver; uma que registra o processo da sua equipe é avaliada pela fidelidade a esse processo. A Anthropic apresenta essa distinção no seu guia sobre avaliação e melhoria de skills.
A separação entre memória e procedimento também ajuda a decidir o que guardar. No artigo sobre Hermes Agent e suas camadas de memória e skills, você encontra mais contexto sobre essa diferença.
1. Extraia o procedimento da conversa com a tarefa resolvida
Revise a sessão e escreva o que o agente recebeu, de quais ferramentas precisou, quais passos seguiu e quais condições a saída precisava cumprir. O skill-creator da Anthropic prevê essa extração a partir de uma conversa, incluindo as correções que levaram ao resultado.
Fonte: skills/skills/skill-creator/SKILL.md at main
Suponha que a tarefa fosse transformar uma tabela em JSON para outro sistema. Mantenha as regras para interpretar colunas, tratar valores incompletos e verificar a saída. Revise separadamente os nomes de arquivo, os caminhos e as exceções que apareceram naquela sessão.
Um caminho fixo pode fazer parte do processo real da sua equipe. Nesse caso, mantenha-o e explique sua função. Se ele só indicava onde estava o arquivo daquela tarefa, transforme-o em uma entrada que o agente precisa identificar.
Escreva a skill com estas ações:
- Descreva qual problema ela resolve e quando deve ser ativada.
- Especifique de qual entrada ela precisa e o que deve revisar antes de agir.
- Organize os passos necessários para resolver a tarefa.
- Explique o motivo das restrições e das verificações.
- Defina qual saída deve entregar e como verificá-la.
Ao terminar, você deve conseguir relacionar cada instrução a uma necessidade do procedimento. Revise especialmente as ordens que surgiram como reação a um erro pontual: elas podem trazer uma regra útil ou introduzir uma exceção específica demais.
2. Prepare casos novos e reserve suas entradas
O guia oficial de avaliação propõe salvar os casos em evals/evals.json, com prompt, expected_output e arquivos opcionais. Ele recomenda começar com dois ou três casos, variar a redação e incluir entradas malformadas ou casos-limite.
Separe os casos que você usa para escrever a skill do conjunto reservado que vai abrir depois de fixar as instruções dela. Se você corrige a receita toda vez que vê uma entrada, essa entrada já participou do desenvolvimento.
Para a transformação de tabelas, prepare casos com diferenças que você consiga interpretar:
| Caso | O que você muda | O que você verifica |
|---|---|---|
| Colunas diferentes | Renomeia os cabeçalhos e muda sua ordem | O agente interpreta os campos sem depender da posição original |
| Entrada malformada | Introduz registros incompletos | Aplica o tratamento previsto sem inventar valores |
| Nova restrição | Muda o formato de saída solicitado | Segue as condições atuais sem carregar o formato anterior |
Defina o resultado esperado antes de executar. Para os campos, especifique a correspondência correta; para os registros incompletos, indique qual tratamento a tarefa exige. Se você aceitar várias respostas válidas, escreva os critérios que elas têm em comum.
Não mude todos os detalhes de uma vez. Um caso que modifica caminhos, estrutura e restrições pode detectar uma falha, mas depois você vai precisar isolar qual mudança a provocou.
3. Congele a skill e compare as duas configurações
Salve uma cópia identificável da skill antes de abrir os casos reservados. A especificação permite registrar uma versão por meio de metadata, embora esse campo seja opcional. Essa cópia será a que você vai avaliar durante toda a comparação.
Execute cada caso com o mesmo prompt e os mesmos arquivos, primeiro em uma configuração e depois na outra. Mantenha o modelo, as ferramentas e as permissões; a diferença que você quer estudar é a presença da skill.
A condição mais importante é o contexto limpo. Use sessões separadas, sem a conversa de desenvolvimento nem os resultados dos testes anteriores. Se o agente já viu a solução, você introduz uma ajuda que contamina a comparação.
O procedimento fica assim:
- Abra uma sessão nova sem a skill e execute o caso.
- Salve a saída, as evidências disponíveis e os dados de consumo.
- Abra outra sessão nova com a cópia congelada da skill.
- Execute o mesmo caso e salve os mesmos dados.
- Anote se a skill foi ativada antes de pontuar o resultado.
Ao final, você deve ter duas execuções comparáveis por caso. Guarde também os erros de ferramentas e os bloqueios por permissões: eles ajudam a distinguir um problema do procedimento de um problema do ambiente.
4. Verifique resultados, tempo e tokens
Avalie condições observáveis. “A resposta parece melhor” deixa margem demais para o gosto pessoal; “o JSON é válido e mantém os registros exigidos” identifica algo que você pode verificar e documentar.
Para condições mecânicas, o guia oficial recomenda scripts de verificação. Você pode verificar o formato, os campos obrigatórios ou as contagens. Para decisões que exigem julgamento, use revisão humana e, quando possível, comparação cega, sem saber qual configuração produziu cada resposta.
Registre os acertos, tempo e tokens junto com as evidências. Uma skill pode melhorar a fidelidade ao procedimento e consumir mais recursos; essa diferença ajuda você a decidir se ela se encaixa no seu trabalho. Se você já está analisando o consumo dos agentes, o artigo sobre os limites do Claude Code traz contexto para essa decisão.
Se você trabalha com o ambiente de skill-creator, a documentação inclui este comando para agregar as avaliações a partir do diretório da ferramenta:
python -m scripts.aggregate_benchmark <workspace>/iteration-N --skill-name <name>Substitua os marcadores pelo diretório da sua avaliação e pelo nome da sua skill. O comando produz benchmark.json e benchmark.md com resultados por configuração.
Repita os casos se quiser estudar a variabilidade. O guia alerta que o desvio padrão só traz informação significativa com várias execuções por caso; uma resposta isolada serve para inspecionar uma falha, mas não descreve sua frequência.
5. Remova instruções para descobrir o que elas acrescentam
Localize as instruções relacionadas às falhas ou a passos que o agente já resolvia sem ajuda. Remova uma de cada vez e execute novamente os casos afetados com contexto limpo. Mantenha uma cópia de cada variante para conseguir atribuir a mudança.
Comece por ordens ligadas ao caso original: caminhos específicos, nomes de colunas, formatos fixos ou passos obrigatórios cujo motivo não está explicado. Se uma instrução não muda os resultados, marque-a para revisão; se surgir uma falha ao removê-la, guarde a evidência que justifica mantê-la.
Revise também a ordem das ações. A Vercel documentou um caso em que mandar consultar primeiro uma skill produziu um page.tsx correto, mas deixou pendentes mudanças em next.config.ts. Explorar primeiro o projeto e consultar a skill depois resolveu as duas partes na avaliação de agentes da empresa.
Quando você incorporar uma falha aos exemplos de desenvolvimento, prepare outro caso reservado para a próxima avaliação. Assim, você evita continuar medindo apenas tarefas cujas soluções já influenciaram as instruções.
Falhas frequentes: ativação, rigidez e contexto herdado
Separe as falhas de ativação das falhas de execução. Se o agente nunca consulta a skill, revise a descrição dela: uma descrição restrita demais pode impedir seu uso, e uma ampla demais pode ativá-la quando não deveria.
Esse problema teve peso no experimento da Vercel sobre Next.js 16: a skill não foi invocada em 56% dos casos e obteve os mesmos 53% de acertos da configuração sem documentação. Com instruções explícitas, chegou a 79%. São resultados daquele experimento, úteis para justificar o registro da ativação como uma verificação independente.
Se a skill é ativada, mas falha quando as entradas mudam, revise as suposições herdadas. Substitua posições fixas por critérios para identificar campos, explique como agir diante de dados incompletos e elimine formatos impostos que contradigam o pedido atual. Depois, repita a comparação.
Cuidado ao reutilizar o chat em que você escreveu a skill: o agente pode se apoiar em correções que nunca chegaram ao SKILL.md. Execute o próximo caso reservado em sessões novas, salve as duas saídas e verifique primeiro se a skill foi ativada; depois, pontue se ela resolveu a tarefa.
O que você achou?
Deixe sua opinião, pergunta ou sugestão. Os comentários são sincronizados com GitHub Discussions .