/skill-eval — avalia uma skill rodando-a de verdade

Harness comportamental: o modelo gera os casos → o script roda a skill via claude -p e grada o determinístico → o modelo grada o ambíguo e dá o veredito. Complementa a skill-lint (estática). Método completo (geração de casos, asserts, grading, pass@k) em references/eval-method.md — leia sob demanda.

Parâmetros

• [nome-da-skill | caminho] — skill sob ~/.claude/skills ou caminho da pasta.
• --samples N — execuções por caso para pass@k (default 1).
• --dry-run — gera/valida o spec + checa o runner, sem executar a skill.

Fluxo

1. Resolver a skill e o spec

Determine a pasta. O eval spec vive em ~/.claude/skills\.skill-evals\<skill>.eval.json.

• Não existe → vá ao passo 2 (gerar). Existe → mostre um resumo e pergunte: reusar ou regerar?

2. Gerar os casos (se preciso) — papel seu

Leia a skill; levante propósito, gatilhos, comportamentos, constraints e fraquezas. Monte 2-3+ casos com gradiente de dificuldade (~30% fácil / 40% médio / 30% hard, ≥1 mirando onde a skill falha) e asserts discriminantes (ver references/eval-method.md §1-3). Prefira asserts determinísticos; use model só para julgamento. Apresente os casos ao usuário e confirme (rodar custa tempo/assinatura). Grave o spec JSON em .skill-evals/<skill>.eval.json.

3. Rodar o motor (determinístico)

pwsh -NoProfile -File "<dir-da-skill>/scripts/run-eval.ps1" -Skill "<nome>" [-Samples N] [-DryRun]

O motor: cria um workspace temp isolado por caso×sample, instala a skill em .claude/skills/<name>/, escreve o setup, executa via claude -p --output-format json (ou marca inline-pending se o CLI não existir — aí você executa a skill inline naquele workdir), captura output+arquivos, grada os asserts determinísticos e calcula pass@k. Devolve JSON { mode, cases[{name,prompt,passAtK, passHatK,samples[{workdir,asserts[{type,ok,pending,evidence}],deterministicPass}]}], summary{cases, deterministicPassCases,passRate,pendingModelAsserts} }. mode ∈ claude -p | inline-pending | dry-run | runner-script. Se vier error no topo (ex.: spec ausente), trate e pare.

4. Gradar os asserts model (julgamento seu)

Para cada assert pending, abra o workdir do sample (transcript + arquivos) e decida PASS/FAIL com evidência citada (contrato em references/eval-method.md §4): burden of proof é da expectation, sem crédito parcial, substância > superfície. Critique também os evals fracos.

5. Relatório + veredito

Renderize EVAL REPORT: passRate + por-caso (asserts que falharam, com evidência) + pass@k/pass^k se -Samples > 1. Veredito: ✅ pronta (passou) ou ⛔ iterar — e diga o que mudar na skill (ancorado nos casos que falharam). Liste sugestões de melhoria dos evals, se houver.

6. Iterar

Após editar a skill, rode de novo o mesmo spec (regressão estável). Repita até verde.

Gates & Guardrails

• Executa de verdade → custa. Sempre confirme os casos antes de rodar; ofereça --dry-run primeiro. Não dispare N samples sem o usuário saber.
• Isolamento. Cada execução roda num temp dir próprio com a skill instalada; o motor não toca o ateliê nem o repo do usuário. claude -p usa --permission-mode acceptEdits nesse sandbox.
• Determinístico é do script; julgamento é seu. Não reimplemente os asserts no chat — chame o .ps1 e consuma o JSON. Asserts model e geração de casos são seus.
• Só avalia. Reportar pass/fail e o que mudar é o escopo; não edite a skill automaticamente (isso é decisão sua + do usuário, não um efeito da eval). Auto-melhorar = futura skill-improve.
• Complementa, não substitui. Rode skill-lint (estática) antes; a skill-eval é o passo comportamental seguinte.

Ativação

scope: global (família da forja). Cópia canônica no ateliê; para ativar em qualquer workspace: /install-skill skill-eval --global.