Uma skill do Claude Code é simples de descrever: um arquivo SKILL.md com um nome, uma descrição e um corpo de instruções, opcionalmente acompanhado de scripts e arquivos de apoio. O agente lê só a descrição até decidir que precisa dela - aí carrega o resto. É um mecanismo elegante. E é exatamente por ser elegante que as pessoas começam a transformar tudo em skill.
Eu sento no Comitê de IA da Bamse e a pergunta que mais ouço não é "como faço uma skill". É uma versão disfarçada de "isso aqui não merece virar uma skill?". E na maioria das vezes a resposta honesta é não. Uma tarefa que você fez uma vez não é um procedimento. É um evento.
Os três critérios
Uma skill só se paga quando o procedimento atende às três condições ao mesmo tempo. Primeiro: repete com frequência. Segundo: é não óbvio ou fácil de errar - tem uma ordem específica, uma pegadinha, um passo que todo mundo esquece. Terceiro: é estável o suficiente para valer a pena documentar, porque uma skill que muda toda semana é dívida, não alavanca. O meu Resume Skills Toolkit nasceu exatamente desse filtro: um procedimento que repete, tem pegadinha de tipografia e quase não muda.
"Uma tarefa que você fez uma vez não é um procedimento. É um evento - e eventos não viram documentação."
Os motivos ruins para criar uma skill são sempre os mesmos dois. "Ficou esperto" - você resolveu algo de um jeito engenhoso e quer congelar isso. E "talvez eu reaproveite um dia" - a aposta de que o futuro vai validar o esforço de agora. Os dois ignoram que o oposto de uma skill útil não é a ausência dela. É só pedir de novo, em linguagem natural, quando precisar.
A descrição é a linha mais importante
Aqui está a parte que quase ninguém leva a sério. O agente decide se invoca a skill lendo a descrição - e só a descrição. O corpo, os scripts, os arquivos de apoio: nada disso entra no contexto até o gatilho disparar. Então uma descrição vaga não é um detalhe estético. Ela quebra o disparo. A skill existe, está perfeita, e nunca é chamada porque a descrição não diz com clareza quando ela serve.
Antes de escrever o corpo, escreva a descrição. Se você não consegue dizer em uma frase quando a skill deve disparar e quando NÃO deve, ela ainda não é uma skill - é uma anotação.
O custo escondido
Toda skill é superfície que você passa a manter. Quando o processo muda, a skill mente. Quando a descrição encavala com a de outra, o disparo fica ambíguo e o agente escolhe errado. Vinte skills medianas atrapalham mais do que três boas, porque cada descrição compete por atenção no momento da decisão. A pergunta certa não é "isso pode virar uma skill". É "eu topo manter isso pelos próximos seis meses". Se a resposta for não, deixe ser um pedido em linguagem natural - é mais barato e nunca fica desatualizado.