Sua skill do Claude nunca dispara: 6 causas, na ordem de investigação

O erro que mais me custou tempo está na documentação em uma frase só: se o frontmatter YAML da skill estiver malformado, o Claude Code carrega o corpo com os metadados vazios. Digitar /minha-skill continua funcionando — as instruções estão ali —, mas o Claude não tem nenhuma description pra comparar com o jeito que você pede as coisas, então ele nunca vai puxar a skill por conta própria. Você testa na mão, funciona, e conclui que está tudo saudável. Não está. Rode claude --debug e o erro de parsing está lá, esperando no log.

É esse o formato da maioria dos bugs de skill. A skill quase nunca é o problema; o roteamento é. Então investigue como roteamento — de "esse arquivo carregou?" pra fora. Nunca comece pelas instruções.

A ordem de investigação

Rode na sequência e pare na primeira surpresa. Dez minutos, sem adivinhação.

1. /context — existe uma linha de Skills ali? Isso já te diz se algo carregou, antes de você começar a teorizar sobre redação.
2. /skills — a sua aparece? O motivo mais comum pra não aparecer: o arquivo está em .claude/skills/minha-skill.md em vez de .claude/skills/minha-skill/SKILL.md. Skill é um diretório com um SKILL.md dentro, não um markdown solto.
3. Olhe o badge no /skills. Se aparecer user-only, é porque disable-model-invocation: true está setado — e, segundo a documentação, isso mantém a description totalmente fora do contexto do Claude. Você digita, ele não dispara. Isso é configuração, não bug, e normalmente vem herdado da skill que você copiou pra começar.
4. claude --debug — pro caso dos metadados vazios lá de cima. Qualquer erro de YAML (dois-pontos sem aspas na description, um tab, aspas curvas coladas de uma doc) cai aqui.
5. Pergunte, dentro da sessão: "quais skills estão disponíveis?" Se ela aparecer com uma description que não lembra nem de longe o jeito que você digita o pedido, achou o bug.
6. claude --safe-mode — sobe com todas as customizações desligadas. Se o problema desaparece, é alguma coisa na sua configuração; se ele sobrevive, pare de culpar o arquivo da skill.

Causa 1 — a description é um rótulo de assunto, não um gatilho

A description é a tabela de roteamento inteira. O guia de autoria da Anthropic é direto sobre a mecânica: ela é injetada no system prompt, então escreva em terceira pessoa — "Generates commit messages by analyzing git diffs", e não "I can help you write commit messages", que a documentação diz causar problema de descoberta na cara dura.

A correção não é escrever "melhor" no abstrato. Abra o histórico do terminal, ache as últimas três vezes em que você pediu esse trabalho com as suas palavras e coloque essas palavras na description. O Claude compara com o jeito que você realmente pede, não com o jeito que você imaginou na hora de escrever a skill.

Causa 2 — sua description foi cortada sem avisar

Essa é invisível e só começa a doer quando você já tem uma coleção de verdade. O Claude Code carrega uma listagem com o nome e a description de todas as skills no contexto, e essa listagem tem um orçamento de caracteres de 1% da context window do modelo. Quando estoura, o Claude Code começa a cortar as descriptions das skills que você invoca menos — ou seja, a skill mais nova, exatamente a que você está debugando, é a primeira da fila a perder as palavras-chave de que precisa. Cada entrada também tem teto de 1.536 caracteres, independente do orçamento.

Rode /doctor pra ver uma estimativa do custo dessa listagem e quem são os maiores contribuintes. Depois escolha uma das três saídas: aumentar o skillListingBudgetFraction (0.02 = 2%), marcar as skills de baixo valor como "name-only" no skillOverrides pra liberar orçamento, ou jogar o gatilho principal pra primeira frase da description, assim o corte come o rabo e não o gatilho.

Causa 3 — está ganhando a cópia errada da skill

Nomes colidem, e a precedência não é a que você imagina: enterprise sobrepõe personal, e personal sobrepõe project. Leia de novo se você trabalha em time. O ~/.claude/skills/deploy/ do seu colega ganha da skill deploy que você commitou no repositório, e nada avisa nenhum dos dois. Uma skill em qualquer nível também sobrepõe uma nativa — jogue um code-review no seu projeto e ele substitui o /code-review do próprio Claude Code.

Duas saídas. Skills de plugin vivem no namespace plugin-name:skill-name, então não colidem com nada. E, num monorepo, um apps/web/.claude/skills/deploy/ aninhado aparece com o nome qualificado /apps/web:deploy, enquanto o /deploy puro continua rodando o da raiz.

Causa 4 — ela foi silenciada nas configurações, não no arquivo

O skillOverrides no .claude/settings.local.json controla visibilidade independente do frontmatter da própria skill — e o menu /skills escreve esse arquivo pra você quando você troca o estado de uma skill com Space. O valor "off" esconde ela do Claude e do menu /. Regras de permissão cortam por outro ângulo: um deny só com Skill mata todas, Skill(deploy *) mata uma. As duas coisas sobrevivem a um restart e nenhuma deixa rastro dentro do SKILL.md.

Causa 5 — ela dispara e depois para de pesar

Sintoma diferente, causa diferente. Quando uma skill é invocada, o conteúdo renderizado entra na conversa como uma única mensagem e fica lá. O Claude Code não relê o arquivo nos turnos seguintes. Ou seja: se a sua skill é escrita como receita de uma vez só, ela já se esgotou no terceiro turno. Escreva regras permanentes, que valem pra tarefa inteira, em vez de passos que só fazem sentido no momento da invocação.

A outra metade disso é a compactação. Quando o contexto enche, o Claude Code reanexa a invocação mais recente de cada skill depois do resumo, guardando só os primeiros 5.000 tokens de cada uma, dentro de um orçamento combinado de 25.000 tokens preenchido de trás pra frente, da mais recente pra trás. Numa sessão longa, a skill que você carregou primeiro pode cair fora inteira. Se uma skill parou de pesar logo depois de uma compactação, é isso — invoque de novo.

Causa 6 — você está debugando numa sessão suja

O guia de boas práticas é explícito nesse ponto: teste numa instância nova, porque o contexto que sobrou de quando você escreveu a skill disfarça os buracos do que você de fato deixou registrado. O teste que vale é uma comparação de linha de base — junte alguns prompts realistas, rode cada um com a skill disponível e de novo com ela desligada, e compare o resultado.

Se você não quiser rodar esse ciclo na mão, /plugin install skill-creator@claude-plugins-official automatiza, incluindo uma etapa de ajuste de description que gera prompts que deveriam e que não deveriam disparar e mede a taxa de acerto. A Anthropic relata que isso melhorou o disparo em 5 de 6 skills públicas, reduzindo tanto falso positivo quanto falso negativo. Foi esse número que me convenceu de que qualidade de description é coisa que se mede, não questão de bom gosto.

Por que isso pesa na review, não só no seu terminal

Se você é dev brasileiro num time distribuído nos EUA ou na Europa, uma pasta .claude/skills/ versionada é um dos poucos artefatos que mostram o seu julgamento de forma assíncrona — ninguém precisa estar no seu fuso pra ver. Só que uma skill que nunca dispara pra mais ninguém é pior do que skill nenhuma: parece ferramenta e se comporta como enfeite. As armadilhas de precedência e de corte que estão aqui em cima são justamente as que fazem a pasta parecer saudável no seu terminal e não fazer nada no de ninguém.

Hoje: escolha a skill de que você menos tem certeza e rode /skills. Confira duas coisas — se a origem dela é onde você acha que é, e se a description contém a frase literal que você usou da última vez pra pedir esse trabalho. Depois abra uma sessão nova, digite essa frase e veja se dispara. Se não disparar, agora você já sabe qual das seis causas abrir.

Fontes

• Claude Code docs — Extend Claude with skills
• Claude Code docs — Debug your configuration
• Claude Docs — Skill authoring best practices
• Anthropic — Improving skill-creator: test, measure, and refine Agent Skills