🧪 Escrever 2-3 test prompts realistas
Depois do draft, crie 2-3 test prompts realistas — o tipo de coisa que um usuário real digitaria. Mostre ao usuário antes de rodar: "Aqui estão alguns casos de teste que eu quero tentar. Estão certos, ou você quer adicionar mais?". Salve os prompts em evals/evals.json ainda sem assertions — elas vêm depois, enquanto as runs rodam.
✗ Prompt artificial
"Format this data"
"Create a chart"
Genérico demais. Não testa nada e nem dispara skills.
✓ Prompt realista
"ok minha chefe mandou um xlsx (tá em Downloads, algo tipo 'Q4 sales final FINAL v2.xlsx') e quer uma coluna de margem de lucro em %. Receita na coluna C, custos na D acho"
Concreto, com backstory, paths e detalhes reais.
evals/evals.json — só prompts, sem assertions ainda:
{
"skill_name": "example-skill",
"evals": [
{
"id": 1,
"prompt": "User's task prompt",
"expected_output": "Description of expected result",
"files": []
}
]
}
⚖️ Rodar com-skill vs baseline no mesmo turno
Para cada test case, dispare dois subagents no mesmo turno: um com a skill, um sem (baseline). Isso importa — não rode primeiro os com-skill e volte depois para os baselines. Lance tudo de uma vez para terminarem por volta do mesmo tempo.
With-skill run
Aponta para o path da skill. Salva em iteration-N/eval-ID/with_skill/outputs/.
Baseline — skill nova
Mesmo prompt, sem skill nenhuma. Salva em without_skill/outputs/.
Baseline — skill existente
A versão antiga. Antes de editar, faça snapshot (cp -r skill snapshot/) e aponte o baseline para ele. Salva em old_skill/outputs/.
💡 Por que o baseline?
Sem comparar com o baseline, você não sabe se a skill agregou alguma coisa. Talvez o modelo já resolvesse o caso sozinho. O baseline é o que separa "a skill ajudou" de "isso teria acontecido de qualquer jeito".
📊 Avaliar: qualitativo + evals quantitativos
A avaliação tem duas frentes. Qualitativa: revisar os outputs no viewer, clicar caso a caso, deixar feedback. Quantitativa: assertions objetivamente verificáveis que produzem um pass_rate. Skills subjetivas (estilo, design) se avaliam melhor só qualitativamente — não force assertions onde precisa de julgamento humano.
✗ Assertion ruim
- ✗Subjetiva: "o output está bonito"
- ✗Nome opaco: "check_1", "assert_x"
- ✗Passa sempre, com ou sem skill (não discrimina)
- ✗Forçada num skill de escrita criativa
✓ Assertion boa
- ✓Verificável: "coluna margem existe e é %"
- ✓Nome descritivo, legível no viewer
- ✓Checada por script, não no olho
- ✓Discrimina with_skill de baseline
eval_metadata.json — com assertions adicionadas:
{
"eval_id": 0,
"eval_name": "margem-lucro-xlsx",
"prompt": "The user's task prompt",
"assertions": [
"Arquivo .xlsx de saída existe",
"Coluna 'margem' presente e formatada como %",
"Valores batem com (C - D) / C"
]
}
🎯 Mostre antes de julgar
Gere o eval viewer com generate_review.py e ponha os outputs na frente do humano antes de você mesmo tentar corrigir. A aba "Outputs" mostra um caso por vez; a aba "Benchmark" mostra pass_rate, tempo e tokens por configuração, com média ± desvio e o delta.
🧠 Como pensar a melhoria
Este é o coração do loop. A grande sacada: a skill será usada um milhão de vezes em prompts diferentes. Você e o usuário iteram em poucos exemplos porque é rápido, mas se a skill só funciona para esses exemplos, é inútil. Generalize a partir do feedback em vez de fazer overfit.
Quatro maneiras de pensar
Generalize do feedback
Evite mudanças fiddly de overfit e MUSTs opressivos. Se um problema é teimoso, tente outras metáforas ou padrões de trabalho — é barato testar e pode render algo ótimo.
Mantenha enxuto
Remova o que não está puxando seu peso. Leia os transcripts, não só os outputs finais: se a skill faz o modelo perder tempo, corte a parte que causa isso e veja o que acontece.
Explique o porquê
Mesmo que o feedback do usuário seja terso ou frustrado, entenda a tarefa e transmita esse entendimento. ALWAYS/NEVER em caixa-alta é yellow flag — reformule com a razão.
Veja trabalho repetido
Se os 3 test cases escreveram um build_chart.py parecido, é sinal forte de bundlar esse script. Escreva uma vez, ponha em scripts/, poupe toda invocação futura.
💡 Tempo de pensar não é o gargalo
O conselho do skill-creator é literal: escreva uma revisão em rascunho, olhe de novo com olhos novos e melhore. Entre na cabeça do usuário, entenda o que ele quer e precisa de verdade. Vale a pena ruminar.
🔁 O loop de iteração
Com a melhoria pensada, rode o ciclo: aplicar → rerodar → revisar → repetir. Cada iteração vai num diretório próprio (iteration-2/, iteration-3/...), incluindo os baselines.
Aplique as melhorias
Edite o SKILL.md com base no feedback e no que você generalizou dele.
Rerode todos os test cases
Numa nova iteration-N+1/, incluindo baselines. Skill nova → baseline sempre without_skill.
Revise com o usuário
Lance o reviewer com --previous-workspace apontando para a iteração anterior, para comparar.
Leia o feedback e repita
Feedback vazio = o usuário achou ok. Foque nos casos com reclamações específicas.
Quando parar
- •O usuário diz que está feliz
- •O feedback está todo vazio (tudo ok)
- •Você não está fazendo progresso significativo
🎚️ Otimização da description
A description é o mecanismo primário que decide se o Claude invoca a skill. Depois de criar ou melhorar, otimize-a para melhor precisão de disparo. Gere ~20 queries de gatilho — um mix de should-trigger e should-not-trigger — e rode o loop, escolhendo a description pela métrica do conjunto de teste.
✓ should-trigger (8-10)
- ✓Mesmo intent, fraseados diferentes (formal/casual)
- ✓Casos onde o usuário não nomeia a skill mas precisa dela
- ✓Usos incomuns e disputas com outra skill onde esta deve vencer
✗ should-not-trigger (8-10)
- →Near-misses: compartilham palavras-chave mas precisam de outra coisa
- →Domínios adjacentes e frases ambíguas
- →Evite negativos óbvios — "escreva um fibonacci" não testa nada
trigger-eval.json — queries com rótulo:
[
{"query": "the user prompt", "should_trigger": true},
{"query": "near-miss tricky prompt", "should_trigger": false}
]
O loop automático
O run_loop.py divide o eval set em 60% train e 40% held-out test, avalia a description atual (rodando cada query 3x para um trigger rate confiável), chama o Claude para propor melhorias com base no que falhou, e reavalia — até 5 iterações. Use o model ID que está rodando a sessão, para o teste de disparo bater com o que o usuário experimenta.
No fim, retorna best_description — escolhida pelo test score, não pelo train, para evitar overfit. Aplique no frontmatter e mostre o antes/depois.
💡 Como o disparo funciona
Skills aparecem em available_skills com name + description, e o Claude decide consultar pela description. Mas ele só consulta para tarefas que não resolve fácil sozinho — "leia este PDF" pode não disparar mesmo com description perfeita. Por isso queries de teste precisam ser substantivas o bastante para o Claude se beneficiar da skill.
✅ Resumo do Módulo
Próximo:
Módulo 4.3 — ⭐ As Melhores Meta-Skills (para criar skills) — skill-creator, find-skills e scaffolding: as ferramentas de quem cria skills e onde cada uma entra no fluxo.