Skills do Claude Code: o que são de verdade e quando não vale criar uma

Passei os primeiros dias com skills do Claude Code criando skill pra tudo. Skill de commit, skill de review, skill de "explica esse arquivo". Achei que era isso: quanto mais skill, mais o Claude sabia fazer. Estava errado, e a maioria delas eu apaguei depois de uma semana.

Este texto é o que eu queria ter lido antes de sair criando: o que uma skill realmente é, por que ela funciona em uns casos e vira ruído em outros, e o critério que uso hoje pra decidir se vale a pena.

O que é uma skill, sem enrolação

Uma skill é uma pasta com um arquivo SKILL.md dentro. Esse arquivo tem um cabeçalho com um nome e uma descrição, e abaixo dele, instruções em texto. É isso. Nada de código mágico, nada de plugin compilado — é instrução escrita, guardada num lugar que o Claude sabe consultar.

Fica normalmente em ~/.claude/skills/nome-da-skill/SKILL.md na sua máquina (vale pra todos os projetos), ou dentro de .claude/skills/ no projeto (vale só ali, e vai junto no git pro time inteiro usar).

Então é só um prompt salvo?

Foi exatamente assim que eu entendi no começo, e é por isso que criei skill demais. A diferença está em uma coisa: um prompt salvo você cola quando lembra. Uma skill o Claude puxa sozinho quando o contexto da conversa bate com a descrição dela.

É aí que mora tanto o poder quanto a armadilha. Se a descrição diz "use ao revisar segurança de código, JWT, secrets, autenticação", o Claude ativa aquilo quando você pede uma auditoria — sem você lembrar que a skill existe. Mas se a descrição é vaga, acontece uma de duas coisas: ou a skill nunca dispara (o Claude não sabe quando ela serve), ou ela dispara na hora errada e injeta instrução que não tinha nada a ver.

A descrição não é enfeite. É o gatilho. Uma skill excelente com descrição preguiçosa é uma skill morta — ela nunca vai ser chamada, ou vai ser chamada quando não devia.

Além disso, uma skill pode carregar arquivos de apoio — um checklist, um exemplo, um trecho de referência — só quando é acionada. Um prompt salvo não faz isso: ou você cola tudo de uma vez e entope o contexto, ou não cola. A skill entrega a instrução certa no momento certo.

Onde skill vale muito a pena

Depois de errar bastante, os casos que sobraram têm três coisas em comum:

1. A tarefa se repete com o mesmo formato

Não "às vezes eu faço algo parecido" — literalmente a mesma coisa, do mesmo jeito, várias vezes. No meu caso: a arquitetura de quatro arquivos que todo comando novo do meu projeto segue. Toda vez era a mesma sequência. Virou skill, e agora eu não preciso repetir a explicação nem torcer pra não esquecer um passo.

2. O "como fazer" é chato de lembrar e fácil de errar

O melhor exemplo que tenho é o deploy. São comandos numa ordem específica, com detalhes que, se você troca um por outro, quebra em silêncio — e você só descobre depois. Isso escrito uma vez num SKILL.md, com os avisos no lugar, vale mais que a minha memória às onze da noite.

3. É conhecimento do projeto que não está no código

Convenções, decisões, o "a gente não faz assim aqui e por isso". Isso não está em nenhum arquivo .ts, e explicar de novo a cada conversa é desperdício. Uma skill de projeto guarda esse contexto e ainda vai junto no git — o time todo herda.

Onde skill só atrapalha

E aqui está o que eu demorei pra aceitar:

• Tarefa que muda toda vez. Se cada execução é diferente, não existe instrução fixa que sirva. Um bom pedido no chat resolve melhor.
• Coisa que você faz uma vez por mês. O custo de manter a skill (ela desatualiza, aponta pra arquivo que mudou de nome) supera o ganho de não digitar o pedido três vezes por ano.
• Só pra não escrever um prompt. Se um prompt de duas linhas resolve, escreve o prompt. Skill pra isso é burocracia com passos extras.

O sintoma de que você exagerou é simples: se você tem uma skill e esqueceu que ela existe, ou ela não estava fazendo diferença, ou a descrição está ruim e ela nunca disparava. Nos dois casos, apagar não te custa nada.

O critério que uso hoje

Só viro skill o que eu já expliquei pro Claude pela terceira vez, do mesmo jeito, e me irritei de repetir. Antes disso, é prompt.

Esperar a terceira vez parece contraintuitivo, mas resolve o problema de raiz: skill boa nasce de dor real e repetida, não de "isso talvez seja útil um dia". As que nasceram de dor, eu ainda uso. As que nasceram de empolgação, apaguei.

Se quiser ver skills reais em uso, tem uma seleção comentada aqui no site — com o que cada uma faz e, importante, quando ela não vale a pena. E quando bater a terceira repetição e você decidir criar a sua, o próximo passo é o tutorial de criar sua primeira skill do zero.