Como testar uma Skill antes de confiar nela

Escrever uma Skill que parece correta na leitura é a parte fácil. Saber se ela realmente funciona como esperado, em pedidos variados, com entrada que não foi pensada com cuidado na hora de escrever, exige um processo de teste que vai além de reler o arquivo em busca de erro óbvio.

Construir avaliação antes de escrever documentação extensa

Uma prática recorrente em desenvolvimento de Skills inverte a ordem intuitiva: em vez de escrever instruções detalhadas primeiro e testar depois, o caminho recomendado é identificar, com casos concretos, onde o agente falha sem a Skill, e só depois escrever o mínimo de instrução necessário para cobrir exatamente essas lacunas. Isso evita documentar problema imaginário que nunca vai aparecer na prática, e mantém a Skill enxuta, cobrindo o que de fato precisa de cobertura.

Uma avaliação simples tem estrutura, não é só “parece que funcionou”

Um caso de avaliação para uma Skill normalmente combina um pedido representativo, os arquivos ou dados de entrada envolvidos, e uma lista de comportamentos esperados na resposta:

{
  "skill": "revisao-de-commits",
  "query": "Gere uma mensagem de commit para este diff",
  "files": ["exemplo.diff"],
  "expected_behavior": [
    "Segue o formato tipo(escopo): descrição",
    "Descreve o motivo da mudança, não só o que mudou",
    "Não inventa contexto que não está no diff"
  ]
}

Definir isso antes de testar transforma “parece que a Skill funcionou” em um critério concreto de aprovação ou reprovação, e permite repetir o mesmo teste depois de qualquer alteração para confirmar que nada quebrou.

Testar com mais de um modelo, quando isso for aplicável

Uma Skill projetada para funcionar em mais de um modelo se comporta diferente dependendo da capacidade do modelo por trás. Um modelo menor e mais rápido tende a precisar de instrução mais explícita para não deixar lacuna; um modelo mais capaz pode não precisar do mesmo nível de detalhe, e excesso de explicação nesse caso só consome espaço de contexto sem melhorar o resultado. Quando uma Skill precisa valer para mais de um modelo, vale conferir se a instrução funciona nos dois extremos, não só no modelo mais forte disponível durante o desenvolvimento.

Casos de borda revelam o que o caso feliz não revela

Testar apenas o pedido óbvio, no formato esperado, raramente expõe onde a Skill é frágil. Entrada incompleta, pedido ambíguo, dado em formato inesperado, ou situação que deveria acionar a fronteira de segurança da Skill em vez de seguir adiante, são os casos que realmente testam se as instruções cobrem o que precisam cobrir. Uma Skill que só foi testada no caminho feliz carrega uma falsa sensação de confiabilidade.

Regressão: garantir que uma correção não quebra outra coisa

Toda vez que uma Skill é ajustada, existe risco de a mudança resolver o problema que motivou o ajuste e, ao mesmo tempo, degradar um comportamento que já funcionava antes. Manter um conjunto pequeno de casos de teste, cobrindo os comportamentos que já foram validados, e rodá-los de novo após qualquer alteração, é o que separa um ajuste controlado de uma correção que introduz problema novo no lugar do antigo.

Confiar depende de observar, não de presumir

O critério final para confiar numa Skill não é “a leitura do arquivo parece coerente”, é o comportamento observado em uso real, repetido o suficiente para não ser coincidência. Isso vale tanto para o primeiro teste quanto para qualquer mudança futura. Uma Skill não testada é uma hipótese sobre o que deveria funcionar. Só o teste, com critério definido antes e revisitado depois, transforma essa hipótese em algo em que vale a pena confiar.