Skill não é usada no Claude Code? Checklist para descobrir o motivo

Fala aí, beleza? Você escreveu a skill, salvou no lugar certo, pediu exatamente a tarefa que ela resolve

e o Claude Code seguiu em frente como se aquele arquivo não existisse

Irrita, né? 😅

A boa notícia é que, na maioria das vezes, quando a skill não é usada o problema não é bug de instalação nem coisa de máquina. É conteúdo: o nome e a descrição que você escreveu não conversam com o vocabulário do pedido que você digitou

O Claude Code carrega no contexto uma listagem com os nomes e descrições das skills, e é contra essa listagem que o seu pedido é comparado. Ou seja: o modelo não abre o seu SKILL.md pra decidir. Ele lê duas linhas de metadado e escolhe

O corpo do arquivo, aquele passo a passo lindo que você caprichou, só entra em contexto depois que a skill é acionada

Então o diagnóstico é sempre o mesmo caminho: primeiro confirmar se a skill existe e é válida, depois atacar nome e descrição, depois conflito com outra skill, e só no fim o orçamento de contexto

Bora por partes

Antes do checklist: confirme se o Claude está lendo a skill ou nem enxergando ela

Tem dois cenários que parecem idênticos do lado de cá do teclado, e o tratamento é completamente diferente:

• Cenário A: a skill nem entra na listagem. Problema de arquivo, de frontmatter ou de flag no frontmatter
• Cenário B: a skill está na listagem, mas não é escolhida. Problema de conteúdo (nome, descrição, escopo, conflito)

A orientação oficial da Anthropic pra esse momento é simples: procure no raciocínio do Claude a linha Reading seguida do nome da skill. Se ela não aparece, a tarefa que você descreveu não casou nem com o nome nem com a descrição

Só que antes de reescrever qualquer coisa, elimine o Cenário A. Faça nesta ordem:

1. Confira o caminho do arquivo. Cada skill precisa ficar na própria pasta, com um SKILL.md dentro. Skill pessoal em ~/.claude/skills/<nome>/SKILL.md (vale em todos os projetos), skill de projeto em .claude/skills/<nome>/SKILL.md (versionada no repositório). Erro comum deste passo: jogar o arquivo solto em ~/.claude/skills/minha-skill.md, sem a pasta. Aí não tem descrição vaga que salve

Formação Recomendada

Formação Claude Code

Domine Claude Code do absoluto zero até o avançado

• 120 aulas
• 4 projetos
• 9h 45min

Conhecer formação

2. Valide o frontmatter. Pra encontrar arquivos cujo YAML não faz parse, roda no diretório de skills:

# skills de projeto
claude plugin validate .claude/skills

# skills pessoais
claude plugin validate ~/.claude/skills

3. Cheque os nomes dos campos, um por um. No frontmatter de skills do Claude Code, os nomes de campos usam palavras minúsculas separadas por hífen, com a exceção de when_to_use. E aqui mora a armadilha: um campo que não bate exatamente com a tabela da documentação é ignorado sem reportar erro. Erro comum deste passo: escrever when-to-use com hífen, achar que está tudo certo porque nada reclamou, e seguir a vida com metade da sua descrição fora do jogo

4. Olhe as duas flags que mudam quem pode invocar. disable-model-invocation: true esconde a skill do Claude até você chamar na mão. user-invocable: false faz o contrário: a skill continua disponível pro Claude, mas some da lista de invocação manual. Se você copiou um exemplo pronto da internet, vale conferir se veio alguma dessas junto 😛

5. Tente invocar na mão. Digite / no campo de prompt: a lista de slash commands inclui os comandos nativos, suas skills, as skills do projeto e as que vêm de plugins instalados. Se a sua aparece ali e roda, o arquivo existe e faz parse. Você acabou de eliminar o Cenário A inteiro

6. Recarregue. Se a skill veio de um plugin que você acabou de mexer, rode claude plugin validate . a partir do diretório do plugin e depois /reload-plugins na sessão aberta, ou simplesmente comece uma sessão nova. Erro comum deste passo: ficar meia hora depurando uma skill que o processo em execução nunca carregou

Eliminou o Cenário A e ela continua sendo ignorada? Ótimo, agora é conteúdo. É aí que o checklist fica interessante

Mapa rápido: sintoma, hipótese e teste

Hipótese 1: a descrição é vaga e não diz quando usar

Sintoma: a skill existe, é válida, aparece na lista do /, roda lindamente quando você chama na mão

e nunca dispara sozinha

Causa provável: a description conta só o que a skill faz, e não conta quando ela deve ser usada

A descrição é literalmente o texto que o Claude compara com o seu pedido pra decidir se aciona a skill. Ela precisa dizer as duas coisas: o que faz e quando usar. Se falta a segunda metade, o modelo tem a ferramenta na mão e nenhum motivo pra pegá-la

Teste que confirma ou elimina:

1. Leia a sua descrição fingindo ser o modelo, sem saber nada do projeto. Ela responde a pergunta "em que situação eu devo usar isso"? Se não responde, achamos
2. Peça a mesma tarefa citando a skill pelo nome. Se assim funciona, e sozinha não, o arquivo está ok e o problema é descrição mesmo

Como resolver: as boas práticas oficiais de autoria mandam escrever em terceira pessoa (a descrição é injetada no prompt do sistema, e ponto de vista inconsistente atrapalha a descoberta), ser específico, incluir termos-chave e os gatilhos ou contextos de uso

O exemplo que a própria documentação de best practices dá é esse:

---
name: pdf-processing
description: Extract text and tables from PDF files, fill forms, merge documents. Use when working with PDF files or when the user mentions PDFs, forms, or document extraction.
---

Repare na engenharia da frase: primeira metade é o que faz, segunda metade começa com "Use when" e lista os gatilhos, incluindo as palavras que o usuário provavelmente vai digitar

É isso que falta na maioria das skills que ninguém consegue acionar

Sobre limites: na especificação de Agent Skills da plataforma, a description não pode ser vazia, tem no máximo 1024 caracteres e não pode conter tags XML. Se o Claude Code local aplica esse número exatamente da mesma forma eu não vou afirmar, porque não achei isso documentado. Mas escrever dentro desse teto te mantém seguro nos dois mundos

Como prevenir: trate a descrição como interface pública da skill, não como comentário. Se você está montando skills do zero, vale entender antes como desenhar uma skill, porque a descrição é o primeiro item desse design

Hipótese 2: o nome não usa o vocabulário do seu pedido

Sintoma: você pede com as palavras que usa no dia a dia e nada acontece. Aí reescreve o pedido com outras palavras, meio por acaso, e a skill dispara na hora

Causa provável: o nome e a descrição estão escritos no vocabulário da documentação, e você fala outro idioma no prompt. Você digita "arruma o changelog", a skill se chama release-notes-generator

Os dois falam da mesma coisa. Só que não se encontram

Teste que confirma ou elimina: repita o mesmo pedido em três formulações diferentes, uma sessão nova pra cada, e observe em qual delas aparece a linha Reading com o nome da skill

1) "atualiza o changelog dessa branch"
2) "gera as release notes dessa branch"
3) "escreve o resumo das mudanças pra tag nova"

Se dispara na 2 e morre na 1 e na 3, confirmado: é vocabulário

Como resolver: o campo name é restrito. Aceita no máximo 64 caracteres, só letras minúsculas, números e hífens, não pode conter tags XML nem palavras reservadas como "anthropic" e "claude"

Então a jogada é dupla:

• escolha pro nome as palavras que você realmente digita, dentro dessas regras
• jogue todos os sinônimos e variações pra dentro da descrição, que é onde cabe texto de verdade

Se o time fala "changelog" e a doc fala "release notes", os dois termos precisam aparecer no metadado. Não tem por que escolher um lado

Como prevenir: antes de nomear, escreva primeiro a frase que você diria pro Claude. Depois tire o nome de dentro dela

Hipótese 3: o escopo é largo demais e a descrição não delimita fronteira

Sintoma: disparo errático. Ela aparece em pedido que não tinha nada a ver, e some justamente no pedido pra qual você criou a skill

Causa provável: skill guarda-chuva. Aquela dev-helper que "ajuda com tarefas de desenvolvimento" 🙂 Uma descrição genérica compete mal com tudo: ela é vagamente parecida com qualquer pedido, então o modelo nunca tem certeza

Teste que confirma ou elimina: monte a suíte que a documentação de skills para empresas recomenda: de 3 a 5 consultas representativas por skill, cobrindo três tipos de caso

• casos em que ela deve disparar
• casos em que ela não deve disparar
• casos ambíguos, de fronteira

Rode e conte os acertos. Se ela dispara nos casos de "não deve", o escopo está largo demais. Se erra os ambíguos dos dois lados, a fronteira não está escrita em lugar nenhum

Como resolver: duas saídas, e elas se combinam

1. Deixe a descrição específica, com os gatilhos explícitos (mesma receita da Hipótese 1)
2. Se a skill realmente cobre vários domínios, organize o conteúdo por domínio dentro dela. A orientação oficial é essa justamente pra o Claude não carregar contexto irrelevante: ao perguntar sobre métricas de vendas, ele lê só os esquemas de vendas

E quando nem isso resolve, quebre em skills menores, cada uma com fronteira própria

Como prevenir: desconfie de toda skill cuja descrição caberia em qualquer projeto seu. Genérico demais é sinônimo de não acionável

Hipótese 4: outra skill parecida está ganhando a disputa

Sintoma: a linha Reading aparece, só que com o nome de outra skill. A sua ficou olhando

Causa provável: duas descrições com termos sobrepostos. Você tem uma skill de revisão de código e outra de revisão de PR, e as duas dizem "revisa mudanças de código procurando problemas"

Pra você a diferença é óbvia. Pro texto que o modelo lê, são gêmeas

Teste que confirma ou elimina:

1. Abra as duas descrições lado a lado e cace os termos em comum. Substantivo repetido é candidato a confusão
2. Rode as consultas de fronteira das duas skills. Se a consulta de fronteira da skill A aciona a B, e a da B também aciona a B, achou o vencedor indevido

Um aviso honesto: a documentação alerta que skills conflitantes podem degradar a performance do agente, mas ela não descreve qual skill vence o desempate, nem se existe ordem de prioridade entre skill pessoal, de projeto e de plugin. Então não adianta procurar regra de precedência, não tem isso documentado. O caminho é remover a ambiguidade na fonte

Como resolver: torne as descrições mutuamente exclusivas. Não basta dizer quando usar, diga quando NÃO usar:

# skill A
description: Reviews individual code diffs for bugs and style issues. Use when the user asks about a specific file or diff. Do not use for whole pull requests.

# skill B
description: Reviews complete pull requests, including description and commit history. Use when the user mentions a PR, MR or merge. Do not use for a single file review.

O "do not use for" faz um trabalho absurdo aqui, porque dá ao modelo um critério de exclusão em vez de só dois textos parecidos competindo

Vale lembrar que o disparo certo é metade do serviço: depois que a skill roda, você ainda precisa revisar o diff que o Claude produziu antes de aceitar

Como prevenir: toda vez que criar uma skill nova, releia as descrições das vizinhas. Skill nova é a principal fonte de regressão em skill antiga

Hipótese 5: sua descrição foi cortada porque a listagem estourou o orçamento

Sintoma: a skill funcionava, você não mexeu nela

e ela parou de disparar depois que você instalou um monte de outras. Ou é uma skill que você usa pouco, daquelas de tarefa mensal

Causa provável: a listagem tem um orçamento de caracteres. A listagem sempre contém todos os nomes, mas se houver muitas skills o Claude Code encurta as descrições pra caber

E o corte não é aleatório: ele começa pelas skills que você menos invoca, então as mais usadas mantêm o texto completo. Sacou a ironia? Quanto menos você usa uma skill, menor a chance de o modelo lembrar de usá-la 😅

Esse orçamento escala em 1% da janela de contexto do modelo

Teste que confirma ou elimina:

1. Rode /context. Ele mostra tudo que ocupa a janela de contexto da sessão por categoria (prompt do sistema, arquivos de memória, skills, subagentes, ferramentas MCP e mensagens). A linha Skills reporta o tamanho da listagem depois de aplicado o orçamento, ou seja, o que o modelo realmente recebeu
2. Rode /doctor. Ele dá uma estimativa do custo de contexto da listagem de skills e mostra os maiores contribuintes. É assim que você descobre quais skills estão comendo o orçamento dos outros

Como resolver: tem três alavancas e elas resolvem problemas diferentes

• skillListingBudgetFraction: aumenta a fração da janela de contexto reservada pra listagem
• SLASH_COMMAND_TOOL_CHAR_BUDGET: variável de ambiente que define o orçamento como contagem fixa de caracteres
• skillListingMaxDescChars: o texto combinado de cada entrada (description mais when_to_use) é limitado a 1.536 caracteres independentemente do orçamento, e esse teto é configurável por aqui

E tem a alavanca do outro lado: marcar entradas de baixa prioridade como name-only em skillOverrides. A skill continua listada pelo nome e libera orçamento pras descrições que importam

Como prevenir: cada skill que você instala por curiosidade cobra aluguel do contexto das suas skills boas. Faça faxina de vez em quando, e rode /doctor depois de instalar um pacote novo de skills

A referência completa desses ajustes está na documentação de skills do Claude Code

Como transformar o checklist em uma rotina de avaliação da skill

Diagnosticar no calor do momento é chato porque você está no meio de uma tarefa, com a cabeça em outra coisa, e acaba mexendo em três lugares ao mesmo tempo sem saber o que resolveu

A saída é virar o jogo: guarde a suíte de avaliação junto com a skill

A recomendação oficial pra uso corporativo é exatamente essa, exigir de 3 a 5 consultas representativas por skill. Monte assim:

1. Duas ou três consultas que devem acionar a skill, escritas no vocabulário real do seu time (não no vocabulário da documentação)
2. Uma consulta que não deve acionar, de preferência algo próximo do domínio de uma skill vizinha
3. Uma consulta ambígua, de fronteira, pra você saber pra que lado ela pende

Rode essa lista em uma sessão nova e anote onde a linha Reading aparece. Você não precisa de ferramenta nenhuma pra isso, precisa de disciplina de rodar sempre que mexer em name ou description

O ganho maior não é nem validar a mudança que você fez

É pegar regressão: a skill que funcionava perfeitamente e quebrou porque você instalou uma skill nova com descrição parecida, ou porque a listagem estourou o orçamento e a sua descrição foi encurtada. Nenhum desses dois casos toca no seu arquivo, e os dois derrubam a skill em silêncio

Sem a suíte, você só descobre semanas depois, no pior momento possível

Conclusão

Quando a skill não é usada, a ordem do diagnóstico é o que economiza seu tempo:

1. Ela existe e é válida? Caminho certo, claude plugin validate, nomes de campo exatos, flags de invocação, tentativa manual pelo /, sessão nova
2. Nome e descrição conversam com o seu pedido? Descrição em terceira pessoa com o que faz mais quando usar, nome no vocabulário que você digita, sinônimos na descrição
3. Tem outra skill brigando? Descrições mutuamente exclusivas, com o "não use para" escrito
4. A listagem estourou o orçamento? /context, /doctor e os ajustes de orçamento

Na esmagadora maioria das vezes você para no item 2, porque descrição sem gatilho é o erro mais comum de todos

Próximo passo prático: abre o SKILL.md agora, reescreve a descrição em terceira pessoa dizendo o que a skill faz e em quais situações ela deve ser usada, lista os termos que você realmente digita

depois abre uma sessão nova e roda as suas consultas de teste

Se a linha Reading aparecer, é festa 😀

até o próximo post!