A Skill de 10 Horas Supera a de 10 Minutos Toda Vez

Achei que escrever uma Skill era só jogar um SKILL.md numa pasta e seguir em frente. Dez minutos, feito. Funcionava bem até eu ver os mesmos erros se repetindo em cada invocação e perceber que não tinha como saber se a Skill estava fazendo o que eu pretendia.

Então Thariq, um dos engenheiros que constroem o Claude Code na Anthropic, postou algo que reformulou tudo: “Usar Skills bem é uma questão de habilidade.”

Essa frase ficou na cabeça porque combinava exatamente com o que eu estava vendo. A diferença entre um arquivo markdown rápido e uma pasta de Skill devidamente estruturada estava aparecendo na qualidade real das saídas, não só na teoria.

Uma Skill é uma pasta, não um arquivo

O equívoco mais comum é achar que uma Skill é igual a um arquivo SKILL.md. Na prática, uma Skill é uma pasta contendo scripts, código de referência, configuração e o arquivo markdown que amarra tudo.

A abordagem interna da Anthropic usa o que eles chamam de divulgação progressiva. Em vez de enfiar tudo num único prompt, eles organizam os arquivos para que o Claude leia apenas o que precisa no momento em que precisa. Um arquivo references/api.md guarda assinaturas de funções que o Claude puxa sob demanda. Um diretório assets/ contém templates de saída para que o prompt nunca precise descrever formatação. Scripts de validação permitem que o Claude teste sua própria saída antes de retorná-la.

Se você abrir o repositório skill-creator, vai ver esse princípio em ação. Os diretórios agents/, references/ e scripts/ ficam ao lado do SKILL.md. A ferramenta que constrói Skills é ela mesma construída como uma.

Os Gotchas importam mais que o corpo do prompt

Thariq chamou a seção de Gotchas de “conteúdo de maior sinal” de uma Skill. Não as instruções principais, não os exemplos. Os Gotchas.

Isso bate com minha experiência. Construí uma Skill sem seção de Gotchas e bati no mesmo erro três vezes seguidas. No momento em que adicionei uma linha documentando aquele padrão específico de falha, parou de acontecer.

O raciocínio é simples. O Claude já sabe a maior parte do que você escreveria no corpo do prompt. Dizer a ele como escrever TypeScript ou formatar JSON é repetir coisas que ele já faz bem por padrão. Mas dizer o que não fazer no seu contexto específico é informação genuinamente nova.

Alguns princípios do post do Thariq que considero confiáveis: não diga o óbvio, porque instruções redundantes podem de fato degradar a performance; evite engessar com passos excessivamente específicos, porque isso mata a capacidade do Claude de se adaptar; e lembre-se de que o campo description não é documentação para humanos, é o input que o Claude usa para decidir quando acionar a Skill.

O Skill Creator transforma “parece funcionar” em “verificado”

A atualização do Skill Creator de duas semanas atrás mudou a forma como penso sobre qualidade de Skill. Você define prompts de teste, estabelece resultados esperados e a ferramenta verifica se a Skill produz de fato os resultados corretos. É teste unitário para prompts.

Adicionei evals a uma Skill que eu usava há semanas. Dois casos de teste que eu assumia que passariam falharam imediatamente. As correções eram pequenas, mas a qualidade das saídas melhorou visivelmente assim que as apliquei.

Há uma distinção útil entre dois tipos de Skills. Skills de uplift de capacidade ensinam o Claude algo que ele não faz bem sozinho. Skills de preferência codificada impõem o workflow ou padrões específicos de um time. O primeiro tipo tem data de validade natural, porque melhorias no modelo eventualmente o tornam desnecessário. O segundo tipo continua valioso enquanto o workflow existir. Evals ajudam você a detectar o momento em que uma Skill de uplift de capacidade vira peso morto.

A ferramenta suporta modo benchmark para rastrear taxas de aprovação e uso de tokens entre atualizações de modelo, execução paralela com múltiplos agentes para evitar contaminação de contexto durante os testes, e um agente comparador que executa comparações A/B cegas de saída com e sem a Skill aplicada.

O retorno composto

Entre as centenas de Skills que já vi e as dezenas que mantenho, um padrão se mantém: o valor de uma Skill vem da iteração, não do rascunho inicial.

A estrutura de pastas é como você molda a janela de contexto do Claude. Gotchas convertem seus erros em conhecimento reutilizável. Evals medem se esse conhecimento ainda se sustenta.

Escrever um SKILL.md leva dez minutos. Adicionar Gotchas de falhas reais, construir casos de eval e incluir scripts de validação leva perto de dez horas. Esse investimento se paga cada vez que a Skill roda. Monte uma hoje à noite. De manhã, ela já terá feito trabalho que você não precisou fazer.