🛠️ Como Criar (o loop)

Antes de escrever qualquer linha, o skill-creator faz 4 perguntas: o que a skill habilita o Claude a fazer, quando ela deve disparar, qual o formato de saída esperado e se vale montar test cases.

A maior parte das skills ruins nasce de intent mal definido. Se a conversa já contém o workflow ("transforma isso numa skill"), extraia das mensagens primeiro e só peça o que falta.

habilita o quê · quando dispara · formato de saída · precisa de testes? · confirmar antes de seguir

Perguntar proativamente sobre edge cases, formatos de entrada e saída, arquivos de exemplo, critérios de sucesso e dependências. Pesquisar em paralelo via subagents quando houver MCPs úteis.

Chegar com contexto pronto reduz o atrito para o usuário. Só escreva test prompts depois de fechar essa parte — entrevista mal feita gera skill que cobre o caso feliz e quebra no resto.

edge cases · formatos in/out · arquivos exemplo · critérios de sucesso · dependências · research paralela

A partir da entrevista, preencher name (identificador), description (gatilho: o que faz E quando usar) e o corpo Markdown com as instruções. Todo "quando usar" vai na description, não no corpo.

A description é o mecanismo primário de disparo. Como o Claude tende a subdisparar, ela deve ser um pouco "pushy" — listar contextos concretos onde a skill deve entrar mesmo sem o usuário pedir explicitamente.

name · description pushy · o que + quando · corpo <500 linhas · compatibility (raro)

Escrever no imperativo, usar theory of mind, explicar o porquê de cada instrução em vez de empilhar MUSTs em maiúscula, e manter a skill geral em vez de colada nos exemplos.

LLMs de hoje são espertos: com o porquê, vão além da instrução rote e resolvem o caso real. ALWAYS/NEVER em caixa-alta é yellow flag — reformule explicando a razão.

imperativo · theory of mind · explicar o porquê · evitar MUSTs · skill geral, não estreita

Escrever um primeiro draft sem travar, depois reler com olhos novos e melhorar. Draft → revisar → melhorar é um ciclo dentro da própria escrita.

O primeiro draft quase nunca é o melhor. Reler distanciado revela instruções redundantes, ambíguas ou que mandam o modelo gastar tempo à toa.

draft rápido · reler distanciado · cortar redundância · clareza · iterar na escrita

Decidir quando extrair recursos para fora do SKILL.md: se 3 execuções repetem o mesmo script, vire scripts/; docs grandes vão para references/ carregadas sob demanda.

Progressive disclosure: metadata sempre no contexto, corpo quando dispara, recursos só quando precisa. Bundlar script repetido poupa toda invocação futura de reinventar a roda.

scripts/ · references/ · assets/ · progressive disclosure · regra das 3 repetições · TOC em docs >300 linhas

Depois do draft, criar 2-3 test prompts realistas — o tipo de coisa que um usuário real digitaria — e mostrá-los ao usuário para validar antes de rodar.

Test prompts artificiais geram avaliações enganosas. Os prompts ficam em evals/evals.json sem assertions ainda — as assertions vêm depois, enquanto as runs estão rodando.

2-3 prompts · linguagem de usuário real · validar com o usuário · evals.json · sem assertions ainda

Para cada test case, disparar dois subagents no mesmo turno: um com a skill, um sem (baseline). Lançar tudo de uma vez para terminarem juntos.

Sem baseline você não sabe se a skill agregou algo. Para skill nova, baseline = sem skill nenhuma. Para skill existente, baseline = a versão antiga (snapshot antes de editar).

with_skill · without_skill · mesmo turno · snapshot da versão antiga · workspace por iteração

Avaliar em duas frentes: qualitativa (revisar os outputs no viewer) e quantitativa (assertions verificáveis que dão um pass_rate). Skills subjetivas se avaliam só qualitativamente.

Boas assertions são objetivamente verificáveis e têm nomes descritivos. Não force assertions em coisas que pedem julgamento humano (estilo de escrita, design).

qualitativo no viewer · assertions verificáveis · pass_rate · nomes descritivos · não overfit em subjetivo

Generalizar a partir do feedback em vez de fazer overfit aos poucos exemplos, manter o prompt enxuto e ler os transcripts (não só os outputs finais).

A skill será usada um milhão de vezes em prompts diferentes. Se ela só funciona para os exemplos do teste, é inútil. Evite mudanças fiddly e MUSTs opressivos.

generalizar · não overfit · manter enxuto · ler transcripts · explicar o porquê · script repetido vira bundle

Aplicar a melhoria → rerodar todos os test cases numa nova iteração → revisar com o usuário → ler feedback → repetir até satisfazer.

O loop para quando o usuário está feliz, o feedback está todo vazio ou você não faz mais progresso significativo. Cada iteração vai num diretório próprio.

aplicar → rerodar → revisar → repetir · iteration-N · previous-workspace · critérios de parada

Gerar ~20 queries de gatilho (mix should-trigger e should-not-trigger), focar em near-misses, rodar o loop de otimização e escolher a description pela métrica do conjunto de teste.

A description decide se a skill dispara. Negativos óbvios não testam nada — os valiosos são near-misses que compartilham palavras-chave mas precisam de outra coisa.

20 queries · should-trigger / should-not · near-misses · 60% train / 40% test · best_description pelo test

Skill cujo trabalho é ajudar você a trabalhar com outras skills — descobrir, criar, testar, otimizar e empacotar. Atua um nível acima da skill comum.

Muita gente cria sem conferir se já existe algo melhor e sem o loop de evals. As meta-skills resolvem isso: descobrir antes, criar com método, validar com dados.

meta-skill · descobrir · criar · testar · otimizar · empacotar

A meta-skill da Anthropic que orquestra o ciclo inteiro — draft → eval → iterate — e traz um otimizador de description separado.

É o eixo central do fluxo de criação. Tudo dos módulos 4.1 e 4.2 sai dela; não improvise um processo paralelo.

draft → eval → iterate · scripts · aggregate_benchmark · run_loop · package_skill

A skill mais instalada do catálogo (1.802.925, vercel-labs). Descobre skills relevantes para uma tarefa antes de você criar do zero.

Evita o erro mais caro de quem cria: gastar horas escrevendo algo que já existe melhor. É a etapa zero do fluxo.

discovery · usar / estender / criar · etapa zero · catálogo de 39.366 skills

Padrão de gerar o esqueleto inicial — SKILL.md com frontmatter e pastas scripts/, references/, assets/ — em vez de digitar tudo na mão.

Acelera o começo e tira a folha em branco. Mas crie só as pastas que vai usar — pastas vazias confundem o modelo e violam o "manter enxuto".

esqueleto · frontmatter pré-preenchido · não criar tudo upfront · podar boilerplate

A sequência que evita retrabalho: find-skills (descobrir) → scaffolding (gerar base) → skill-creator (criar e iterar) → otimizador de description (afinar disparo).

As três não competem, se encadeiam. Usá-las fora de ordem é onde nascem as skills de menos de 100 installs.

descobrir → base → criar/iterar → otimizar → empacotar · regra de ouro

Um resumo situação → ferramenta: "preciso de uma skill pra X" → find-skills; "vou criar" → skill-creator; "não dispara quando devia" → otimizador de description.

Decisão rápida na hora certa. Instale as três e, como o Claude tende a subdisparar, mencione-as explicitamente nas primeiras vezes até virar reflexo.

situação → meta-skill · instalar as três · pro tip de disparo · package_skill

As 4 perguntas aplicadas ao caso "margem-xlsx": habilita o quê, quando dispara, formato de saída e se vale testar. Saída verificável → vale testar.

A pergunta 4 decide o resto do walkthrough. Transformações de arquivo e geração de código merecem evals; estilo/arte, não.

habilita · quando dispara · formato · vale testar · extrair da conversa · confirmar

Escrever o draft completo: name, description pushy (o que faz E quando usar) e corpo no imperativo explicando o porquê.

A description é o gatilho. "Mexe em planilhas" subdispara; listar verbos + contextos ("margem, lucro... mesmo sem pedir coluna") cobre os near-triggers.

name · description pushy · corpo imperativo · explicar o porquê · não chutar colunas

2-3 prompts como um usuário real escreveria — com backstory, paths e detalhes — salvos em evals/evals.json sem assertions ainda. Template JSON pronto.

Prompts artificiais geram avaliação enganosa. Valide com o usuário antes de rodar — é barato e evita rodar tudo à toa.

2-3 prompts · linguagem real · paths e backstory · evals.json · validar antes

Enquanto as runs rodam, escrever assertions objetivas e com nomes descritivos no eval_metadata.json — checadas por script de preferência. Template pronto.

"a planilha ficou boa" é subjetivo; "valores batem com (C-D)/C" é verificável e discrimina with_skill de baseline.

assertions verificáveis · nome descritivo · checada por script · discrimina · não subjetivo

Dois subagents no mesmo turno por test case (com skill / sem skill = baseline), saída organizada por iteração e eval, com total_tokens e duration_ms no timing.json.

Lançar juntos evita viés. O timing só pode ser capturado quando a notificação chega — processe cada uma na hora.

with_skill / without_skill · mesmo turno · workspace por iteração · timing.json

Timeline numerada: grade cada run → agregue o benchmark → abra o viewer antes de você julgar → leia o feedback e generalize → rerode em iteration-2.

No caso, as 3 runs escreveram um calc_margem.py quase igual — sinal de bundlar. Na iteração 2 o pass_rate subiu e os tokens caíram.

grading.json · aggregate_benchmark · generate_review · feedback · bundle de script repetido

run_loop.py divide o eval set em 60% train / 40% test, avalia a description (3 runs por query), propõe melhorias com base no que falhou e reavalia, até 5x.

O disparo é estocástico; 3 runs dão um trigger rate estável. Use o model ID da sessão para o teste bater com o que o usuário experimenta.

run_loop · 60/40 · 3 runs/query · propor → reavaliar · model ID da sessão · background

~20 queries realistas, metade should-trigger e metade should-not. O ouro está nos near-misses — frases que compartilham palavras mas precisam de outra coisa.

"Margem de erro de uma pesquisa" usa "margem" mas não é lucro em planilha — força a description a discriminar. Negativos óbvios não ensinam nada.

should-trigger 8-10 · should-not 8-10 · near-misses · evitar óbvios · trigger-eval.json

Skills aparecem em available_skills com name + description e o Claude decide consultar — mas só consulta para tarefas que não resolve fácil sozinho.

"Leia este PDF" pode não disparar nem com description perfeita. Suas queries de teste precisam ser substantivas (multi-step, especializadas).

available_skills · só tarefas não-triviais · queries substantivas · subdisparo · pushy

Dar dois outputs a um agente independente sem dizer qual é qual, deixá-lo julgar a qualidade e depois analisar por que o vencedor venceu.

Por ser cego, não favorece "o novo" só por ser novo. É opcional e exige subagents — guarde para quando a dúvida for cara.

anonimizar · julgar qualidade · por que venceu · opcional · subagents · review humano basta

O benchmark traz pass_rate, tokens e tempo por config, com média ± desvio e delta. A passada de analista revela o que a média esconde.

Assertion que passa com E sem skill não mede nada e infla o pass_rate; desvio alto pode ser flaky; pass_rate alto pode esconder explosão de tokens.

pass_rate · delta · não-discriminante · variância/flaky · tradeoff de tokens/tempo

Pegar o best_description (escolhido pelo test score, não pelo train), aplicar no frontmatter, mostrar antes/depois e empacotar com package_skill.

Escolher pelo train premiaria a description que decorou os exemplos. O held-out test simula o mundo real — é o que separa generalizar de brilhar só no laboratório.

best_description · test score > train · otimizar só depois de pronta · revisar eval set · package_skill