O Claude Code ignorou minha skill 5 vezes. 1 linha resolveu

Uma skill do Claude Code pode rodar perfeitamente quando você chama pelo nome e mesmo assim nunca carregar sozinha. A nossa rodou todas as vezes que digitamos o nome e foi ignorada todas as vezes que pedimos a mesma tarefa com palavras normais. Vimos ela ser ignorada, lemos o porquê e reescrevemos a única linha que resolveu.

Uma skill é um conjunto salvo de instruções que o Claude Code carrega por conta própria quando o seu pedido combina com ela. O que decide essa combinação é uma linha que o Claude lê antes de escolher, e não são as suas instruções. Os seis passos abaixo levam você do prompt que vive redigitando até uma skill que carrega sozinha, mais um teste de vinte pedidos que pega uma skill ignorada antes que o seu time pegue.

Teste (mesmo pedido, sessões novas)	Skill carregada
Chamada pelo nome (/release-notes)	2 de 2
Palavras normais, descrição original	0 de 5
Palavras normais, descrição reescrita	5 de 5

Uma skill é uma pasta com um único arquivo dentro, o SKILL.md. O arquivo começa com um cabeçalho curto (um nome e uma descrição de uma frase), seguido das instruções. Funciona como uma função: quem chama lê a assinatura e a docstring, e o corpo só roda quando é chamado. Salve na sua pasta pessoal para ter em todos os projetos, ou dentro do repositório para que todo mundo que trabalha nele receba.

Comece pela tarefa, não pelo arquivo. Escolha o prompt que você vive redigitando e anote exatamente a saída que quer. O nosso eram as release notes da semana: os commits desde segunda, agrupados por área, sem as tarefas de manutenção, uma linha por mudança com o número do pull request. No repositório open source Hono, esse prompt longo gerou notas limpas para oito correções de bugs naquela semana, e essa saída virou o alvo que a skill precisava acertar.

Crie .claude/skills/release-notes/SKILL.md no seu projeto: uma pasta skills dentro da pasta oculta .claude, uma pasta com o nome da skill e o arquivo da skill dentro dela. A pasta importa. Um release-notes.md solto não carrega de jeito nenhum, e a documentação lista isso como a primeira coisa a verificar.

O cabeçalho são algumas linhas com rótulos entre duas fileiras de traços, e precisa começar na primeira linha do arquivo, senão o Claude Code o ignora. O nosso tinha um nome, release-notes, e a descrição que a maioria das pessoas escreveria:

---
name: release-notes
description: Generates changelog documents from repository history.
---

Abaixo do cabeçalho vão as instruções, em passos numerados, os mesmos que você daria a uma pessoa nova no time. A nossa tem cinco: achar os commits desde segunda, descartar os commits chore e docs, agrupar por escopo de conventional commit, escrever uma linha simples por mudança e gerar um bloco com título e um resumo curto no topo. A Anthropic recomenda manter essa parte curta. Você não precisa reiniciar: o Claude Code pega uma skill nova ou editada na sessão em que você já está.

Teste pelo nome: digite uma barra, escolha a skill no menu, aperte enter. Em sessões novas, a nossa leu o log de commits, agrupou as correções por área e escreveu as notas exatamente como queríamos, todas as vezes. O problema é que você, e todo o seu time, precisam lembrar o nome dela.

Um colega não vai digitar o nome da skill. Vai abrir uma sessão nova e pedir do jeito que pediria a você. Então teste isso: abra uma sessão nova (uma conversa nova, sem nada carregado) e peça a tarefa com as suas próprias palavras. Tem que ser nova, porque uma skill já usada fica na conversa e um teste nessa sessão não prova nada.

Digitamos "what did we ship this week?". O Claude rodou o log de commits por conta própria e escreveu um resumo do jeito dele, sem nenhum sinal da skill. As respostas não eram ruins, mas mudavam de uma execução para outra: uma contava a partir de segunda, outra a partir da última tag de release e incluía uma mudança de documentação que a skill teria descartado. Em cinco sessões novas, a skill foi ignorada nas cinco.

Cinco execuções são uma demonstração, não uma estatística. Mas uma skill que funciona pelo nome e é ignorada todas as vezes com palavras normais não está fazendo o trabalho dela, e como ela passou no teste pelo nome do passo dois, você nunca pensaria em olhar.

Antes de mudar uma palavra, faça três verificações:

1. /skills lista todas as skills que a sessão enxerga. Procure a sua. A nossa estava listada e ativa, mas o setup tinha 277 skills, e várias skills de plugins combinavam com "release" antes da nossa.
2. claude --debug grava um log detalhado do que o Claude Code carrega. Procure as linhas de skills. O nosso mostrou a skill do projeto carregada, e também um aviso de que a lista de skills estava acima do orçamento, então algumas descrições são cortadas.
3. claude plugin validate .claude/skills confere se o cabeçalho está bem formado. Esta importa: um cabeçalho quebrado ainda deixa a skill rodar pelo nome, mas o Claude não consegue mais combiná-la sozinho. A nossa passou.

Verificação	O que ela diz	Nosso resultado
/skills	A skill está visível e ativa?	Listada, ativa (277 skills)
--debug	Carregou? A lista foi cortada?	Carregada; aviso de lista acima do orçamento
plugin validate	O cabeçalho é interpretado?	Passou

Com o arquivo carregado e o cabeçalho válido, a causa é a descrição. Até decidir carregar uma skill, o Claude não lê as suas instruções. Ele lê uma linha por skill, o nome e a descrição, e compara com as suas palavras. A nossa dizia "generates changelog documents from repository history"; o pedido dizia "what did we ship this week". As duas frases não têm nenhuma palavra em comum. O Claude nunca leu as nossas instruções; leu uma linha, e essa linha não usava as nossas palavras.

O aviso de orçamento significa que o Claude Code corta descrições para caber, começando pelas menos usadas, e uma skill recém-criada é a menos usada de todas. Verifique se a sua sobreviveu: a nossa sim, já que pedidos com as palavras dela ainda a carregavam.

Escreva a descrição para o momento em que alguém pede, não para o arquivo. Diga o que a skill faz, quando usar e as palavras que as pessoas realmente digitam. A nossa ficou assim:

description: Writes this week's release notes from git log, grouped by scope (router, css, jsx). Use when the user asks what we shipped, what changed this week, for release notes, a changelog, or a summary of recent commits.

O guia de autoria da Anthropic acrescenta uma regra: escreva na terceira pessoa ("Writes"), nunca "I can help" nem "You can use this".

Depois prove numa sessão nova com o mesmo pedido. "What did we ship this week?" agora carregou a skill antes de o Claude tocar em qualquer coisa, e as notas saíram no nosso formato, em cinco de cinco sessões novas.

Faça também uma linha de base: desligue a skill com um skill override no arquivo de configurações local (ele esconde a skill sem apagá-la). Com ela desligada, o Claude voltou ao próprio resumo; com ela ligada, a skill carregou. Foi a skill que fez a diferença, não sorte.

O limite: uma descrição que combina com coisas demais faz a skill disparar onde não deveria. Adicione as palavras que você realmente usa, não todas as que consegue imaginar.

Um pedido provou a correção; uma skill da qual um time depende é pedida de muitas formas. O skill-creator da Anthropic descreve o teste: vinte pedidos, uma mistura de os que devem carregar a skill e de quase-acertos que não devem. Um quase-acerto parece próximo, mas é outro trabalho, como "write a commit message for my staged changes". Rode cada pedido na sua própria sessão nova e anote se a skill carregou. O script do próprio skill-creator não enxergou a skill na nossa versão do Claude Code, então rodamos os mesmos vinte pedidos com um script curto nosso.

Descrição	Pedidos que deviam carregar e carregaram	Quase-acertos que carregaram
Original	4 de 10	0 de 10
Reescrita	10 de 10	0 de 10

Antes da reescrita, a skill só carregava nos pedidos que já continham "release notes", "changelog" ou "release": a combinação por palavras do passo quatro, à vista de todos. Depois da reescrita, carregou em todos os pedidos que deviam carregá-la e continuou fora de todos os quase-acertos.

Para uma skill que não pode falhar nunca, force. Digite o nome dela, ou adicione um hook (um pequeno script que o Claude Code roda em um momento fixo, aqui a cada mensagem que você envia) cuja saída diga ao Claude para usar a skill nessa tarefa. Com o hook no lugar, até a descrição original carregou no pedido em palavras normais. O limite: cada execução de teste gasta uso de verdade e um hook adiciona uma linha a cada mensagem, então reserve isso para as poucas skills que realmente precisam disparar. Rode a sua lista de novo sempre que mudar a descrição.

Nossa skill de release notes funcionou todas as vezes pelo nome, foi ignorada em toda sessão nova com palavras normais, e uma linha reescrita fez ela carregar todas as vezes. O motivo: o Claude lê uma linha por skill antes de decidir, e combina com as suas palavras, não com as suas intenções.

Uma skill compensa para uma tarefa que você repete com uma saída fixa: notas semanais, a descrição de um pull request, um checklist de release. Não compensa para uma pergunta pontual, e não é a ferramenta para uma regra que precisa valer sempre; isso é trabalho de um hook. Um monte de skills sem uso também custa, porque com skills demais o Claude Code começa a cortar descrições, as menos usadas primeiro. Uma boa descrição aumenta as chances, mas não fará uma skill disparar para um trabalho para o qual ela nunca foi feita, e um punhado de execuções é uma demonstração, então a sua lista de pedidos de teste é a verificação de verdade.

A regra: escreva a descrição com as palavras que você realmente digita quando pede a tarefa.