Skill do Claude Code parou de ser acionada depois que você editou? Como achar o que quebrou

Você mexeu na skill só pra melhorar um detalhe, salvou, pediu a mesma coisa de sempre e o Claude Code fez de conta que ela nunca existiu 😐

Ontem ela era acionada sozinha, hoje o pedido idêntico não puxa nada

E aí bate aquela vontade de culpar a ferramenta

Só que, na prática, quase nunca é bug do Claude Code

É quase sempre uma mudança pequena que você mesmo fez: uma palavra que sumiu da description, o nome da pasta que mudou, um campo do frontmatter que entrou sem você pensar muito, ou a skill que foi parar num escopo diferente do que você imagina

Este post é um roteiro de diagnóstico, do mais provável pro menos provável

A ideia é você ir descendo a lista, confirmando cada hipótese, e no fim usar um método de voltar a edição um pedaço por vez até achar exatamente a alteração culpada

Bora?

Antes de tudo: confirme se a skill ainda carrega na sessão

Existe uma diferença gigante entre dois problemas que parecem iguais de fora:

• a skill não carregou na sessão
• a skill carregou, mas o Claude não escolhe ela

Se você tentar consertar o segundo caso quando o problema é o primeiro, vai reescrever description a tarde inteira à toa

Então o passo zero é sempre olhar a listagem

A forma mais rápida é perguntar pro próprio Claude quais skills estão disponíveis (pode ser em português mesmo), e ver se a sua aparece ali

Depois disso, o /context mostra o que realmente foi carregado naquela sessão, separado por categoria: system prompt, ferramentas do sistema, ferramentas MCP, subagents com a origem de cada um, arquivos de memória, skills e as mensagens da conversa

É o raio-x da sessão

Se a categoria de skills não tem a sua, o problema é de carregamento, não de gatilho

O /doctor complementa: ele roda um checkup de setup, diagnostica e aplica correções de instalação e configuração em vez de só imprimir relatório, encontra skills, servidores MCP e plugins não usados versus o custo de contexto deles, e ainda dá uma estimativa do custo de contexto da listagem de skills e dos maiores contribuintes

Guarda esse detalhe do custo de contexto, ele volta lá embaixo 👀

"Mas será que eu preciso reiniciar depois de editar?"

Essa é a primeira explicação que todo mundo tenta, e ela não bate com a documentação

O Claude Code monitora os diretórios de skills e aplica as edições na sessão em andamento

Adicionou, editou ou removeu uma skill em ~/.claude/skills/, no .claude/skills/ do projeto ou num .claude/skills/ dentro de diretório passado com --add-dir? A mudança é capturada na sessão atual, sem restart

Ou seja: "acho que ficou em cache" não é o diagnóstico, é a desculpa que atrasa o diagnóstico

Como prevenir: toda vez que editar uma skill, faz a checagem da listagem antes de sair testando prompt

Dez segundos ali economizam meia hora de chute

Sintoma: a skill aparece na lista, mas o Claude nunca a escolhe sozinho

Esse é o caso mais comum de todos quando o gatilho quebra depois de uma edição

Skills são model-invoked: o Claude escolhe a skill quando o seu pedido casa com a description dela

E as descriptions são carregadas no início da sessão

Então a description não é enfeite nem documentação bonitinha, ela É o gatilho

Se você "enxugou" a descrição pra deixar mais elegante, tem grande chance de ter jogado fora justamente as palavras que faziam o casamento acontecer

A doc é clara sobre o formato: a description precisa dizer o que a skill faz e quando usá-la, incluindo os termos-gatilho que o usuário diria

O exemplo oficial é esse aqui:

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.

Repara na segunda frase

Ela existe só pra listar as palavras que o usuário realmente digita: PDFs, forms, document extraction

O teste mental: quais palavras sumiram?

Abre a versão antiga e a nova lado a lado e responde uma pergunta só

Quais termos que eu uso no dia a dia estavam na descrição antiga e não estão mais?

Se a antiga dizia "use quando o usuário falar em revisar PR, revisar diff ou code review" e a nova virou "revisa código", pronto, você achou o culpado

Um formato que funciona bem:

---
name: revisao-pr
description: Revisa diffs de pull request procurando bug de lógica, código duplicado e teste faltando. Use quando o usuário pedir revisão de PR, revisão de diff, code review ou falar em "olha esse commit pra mim".
---

O limite é de 1024 caracteres na description, então tem espaço de sobra pra listar os termos-gatilho sem escrever um TCC

Se você quiser se aprofundar só nessa parte, tem um post inteiro aqui sobre como escrever a descrição da skill pra ela ser acionada

Como prevenir: pode encurtar a description, mas nunca tire a parte do "quando usar"

Essa parte é o gatilho, o resto é contexto

Sintoma: você renomeou algo e o comando mudou de nome sem avisar

Aqui mora uma pegadinha que confunde muita gente

Em skill pessoal e de projeto, o comando que você digita vem do nome da PASTA, não do campo name do frontmatter

O name ali define apenas o rótulo exibido nas listagens

Caminho manda, campo não

~/.claude/skills/<nome-da-skill>/SKILL.md
.claude/skills/<nome-da-skill>/SKILL.md

Então se você renomeou a pasta pra deixar "mais organizado", o comando mudou junto, mesmo que o name continue igualzinho lá dentro

E em skill de plugin é o contrário: aí o name define o último segmento do comando

Um my-plugin/skills/review/SKILL.md com name: fancy vira /my-plugin:fancy

As regras de formato do campo name:

O formato Agent Skills também tem regras duras pro name:

• só letras minúsculas, números e hífens
• máximo de 64 caracteres
• não pode começar nem terminar com hífen
• não pode ter hífens consecutivos

Tome cuidado com aquele rename "inofensivo" que coloca um Revisao_PR ou um skill--nova no lugar do nome antigo

Solução: confere o caminho completo da pasta e confere o SKILL.md dentro dela, os dois, sempre

Como prevenir: quando for renomear, renomeie pasta e rótulo com consciência do efeito de cada um, e já anote qual comando passa a existir depois disso

Sintoma: dois campos do frontmatter desligam justamente o acionamento

Tem dois campos que fazem exatamente o que você está sentindo, e é fácil ligar um deles copiando frontmatter de outra skill

• disable-model-invocation: true: só você invoca, o Claude não aciona sozinho
• user-invocable: false: só o Claude invoca

Por padrão, os dois podem invocar qualquer skill

Ou seja: se a skill funciona quando você chama na mão mas nunca é acionada sozinha, olha o disable-model-invocation antes de mexer em qualquer outra coisa

É literalmente o botão de desligar o gatilho automático

E quando o SKILL.md está intacto?

Aí entra o skillOverrides

Com ele dá pra setar uma skill como off (esconde) ou como user-invocable-only (restringe), sem editar o SKILL.md

Isso existe justamente pras skills cujo arquivo você não quer tocar, tipo as que vêm de repositório compartilhado

E é por isso que essa checagem importa: você pode passar a tarde comparando SKILL.md antigo com novo, achar tudo igual, e o comportamento ter mudado por causa de uma configuração que nem está no arquivo

Como prevenir: revisa frontmatter e overrides ANTES de culpar a description

É mais rápido e elimina a hipótese com uma olhada só

Sintoma: outra skill com o mesmo nome está ganhando

Quando duas skills têm o mesmo nome, existe uma ordem de precedência, e a de nível mais alto vence

O exemplo da própria doc deixa claro: com uma skill deploy em ~/.claude/skills/ e outra no .claude/skills/ do projeto, o /deploy roda a pessoal

Sacou o cenário clássico? Você editou a do projeto, testou, e nada mudou

Não mudou porque quem está rodando é a cópia pessoal, que você nem lembrava que existia

O caso das skills embutidas:

Uma skill sua sobrescreve uma skill embutida de mesmo nome, mas não os aliases dela

Uma code-review no .claude/skills/ do projeto substitui a /code-review embutida, porém digitar o alias embutido /review nunca roda a sua skill

Detalhe cruel pra quem tem o alias no dedo 😅

E as skills de plugin?

Essas usam namespace, no formato plugin-name:skill-name, e por isso não colidem

Uma skill deploy vinda de plugin carrega junto com uma deploy do projeto, as duas convivem

Solução: localize TODAS as cópias com aquele nome, nos dois caminhos, e decida qual escopo fica

Como prevenir: nomes distintos por escopo

Se é a versão pessoal, dá um nome que diga isso

Sintoma: a description foi cortada pelo orçamento de caracteres da listagem

Essa é a causa menos óbvia e a mais sacana, porque ela quebra skills que você nem tocou

A listagem de skills tem um orçamento de caracteres

Todos os NOMES de skill sempre entram no contexto, mas as descriptions são encurtadas pra caber nesse orçamento

E adivinha o que some quando encurta? Exatamente as palavras-chave que o Claude usaria pra casar o seu pedido

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

Então se você foi acumulando skill, plugin e afins, o setup cresceu, o orçamento não acompanhou na mesma proporção, e as descrições começam a ser podadas

A skill continua lá, o nome continua aparecendo, e o gatilho evapora

Como resolver:

Dá pra aumentar o orçamento de duas formas:

• o setting skillListingBudgetFraction (ex.: 0.02 pra 2%)
• a variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET

E tem como confirmar que é isso mesmo: quando a listagem passa do orçamento, o Claude Code grava um aviso no log de debug, visível com --debug

Se o aviso está lá, não adianta reescrever description, o problema é de espaço

Como prevenir: mantenha as descriptions objetivas (o que faz + quando usar + termos-gatilho, sem encher linguiça) e vigie o custo de contexto pelo /doctor, que estima o custo da listagem e mostra os maiores contribuintes

Sintoma: funciona na sua máquina, some no ambiente remoto ou no repositório

Às vezes a skill não quebrou

Ela só nunca esteve onde você precisava que ela estivesse

Skill que só existe em ~/.claude/skills/ da sua máquina não é encontrada em sessões remotas

E cada execução de routine começa como uma sessão remota nova, então o Claude Code reporta skill não encontrada

As alternativas oficiais são três:

• habilitar a skill na conta claude.ai (vale pro Cowork e pras sessões cloud)
• commitar a skill em .claude/skills/ do repositório
• distribuir em plugin declarado no .claude/settings.json do repositório

Se você foi pelo caminho do plugin, dois detalhes ajudam

O campo allowed-tools do frontmatter controla quais ferramentas a skill pode usar sem aprovação por uso, e o Claude Code aplica o allowed-tools de uma skill de projeto sempre que você ou o Claude invocam a skill, inclusive em execução com -p em pasta nunca confiada

E existe validação antes de distribuir:

claude plugin validate ./seu-plugin

Ele imprime ✔ Validation passed ou ✔ Validation passed with warnings

Avisos não reprovam, e --strict trata aviso como erro

Campos não reconhecidos viram aviso, não erro, então uma chave escrita errada no frontmatter passa batido se você não olhar a saída

Como prevenir: decidir o escopo ANTES de editar

"Onde essa skill precisa rodar?" é uma pergunta de 5 segundos que evita um debug de uma hora

Como isolar a alteração culpada voltando um pedaço por vez

Beleza, e se você passou por todas as hipóteses acima e ainda não achou?

Aí é hora do bisect manual

A lógica é a mesma do bisect de código: em vez de olhar pro arquivo inteiro tentando adivinhar, você volta pedaços até o comportamento bom reaparecer, e o último pedaço que você mexeu é o culpado

1. Recupere a versão que funcionava. Se a skill está versionada, o histórico do arquivo já te entrega tudo:

git log --oneline -- .claude/skills/minha-skill/SKILL.md
git diff HEAD~1 -- .claude/skills/minha-skill/SKILL.md

Se não está versionada, procure uma cópia antiga, backup, o que tiver

O erro comum deste passo: tentar reconstruir de memória como era a description antiga

Você vai lembrar do sentido e esquecer justamente da palavra-gatilho que sumiu

2. Fixe o pedido de teste antes de qualquer coisa. Escolha UM prompt, exatamente como você pediria no dia a dia, e escreva ele num arquivo de rascunho pra usar sempre igual

O erro comum deste passo: testar cada rodada com um pedido levemente diferente

Aí você não sabe se mudou a skill ou se mudou o pedido, e o teste inteiro perde o valor

3. Volte SÓ a description e teste. Nada de frontmatter inteiro, nada de renomear pasta, só a descrição antiga de volta

Como as edições são captadas na sessão atual, você testa direto

O erro comum deste passo: mudar duas coisas de uma vez "pra ganhar tempo"

Se funcionar, você não vai saber qual das duas resolveu, e vai carregar a outra pra sempre por medo

4. Se voltou, reaplique a melhoria em fatias. Coloque de volta um trecho da descrição nova por vez, testando entre cada fatia

A fatia que mata o gatilho é a resposta

O erro comum deste passo: parar quando "voltou a funcionar" sem descobrir o porquê

Daqui a duas semanas você repete a mesma edição e cai no mesmo buraco

5. Se não voltou, restaure o frontmatter inteiro. Aí entram os campos que desligam invocação, o name, o allowed-tools

O erro comum deste passo: olhar só o SKILL.md e esquecer do skillOverrides, que muda comportamento sem tocar no arquivo

6. Ainda não? Restaure o nome da pasta. Lembra que em skill pessoal e de projeto o comando vem do diretório

O erro comum deste passo: renomear a pasta e deixar a versão antiga lá do lado, criando duas skills concorrentes

7. Por último, o local. Pessoal ou projeto, e se existe cópia com o mesmo nome no outro escopo brigando pela precedência

O erro comum deste passo: assumir que a cópia pessoal não existe porque você não lembra de ter criado

Esse método é chato, eu sei

Mas é MUITO mais rápido que reescrever a skill do zero e torcer

E tem um bônus: você aprende qual pedaço da sua skill realmente segura o gatilho

É o mesmo tipo de disciplina que salva a vida quando o Claude Code repete o mesmo erro depois de você corrigir: mudar uma variável por vez em vez de sacudir o setup inteiro

Ligando o log de debug para ver a decisão por trás do gatilho

Quando a hipótese é orçamento estourado, o log resolve a discussão

1. Abra a sessão gravando o log num caminho conhecido:

claude --debug-file /tmp/claude.log

2. Acompanhe o arquivo em outro terminal:

tail -f /tmp/claude.log

3. Já abriu a sessão sem a flag? Roda /debug no meio da sessão pra habilitar o log e descobrir o caminho do arquivo

O erro comum deste passo: fechar tudo e começar de novo achando que sem a flag não dá mais pra logar

Dá 🙂

4. Procure o aviso de estouro do orçamento da listagem. É ele que confirma que as descriptions estão sendo encurtadas, ou seja, que o problema não é o texto que você escreveu, é o espaço que sobrou pra ele

Se o aviso aparecer, o caminho é skillListingBudgetFraction ou SLASH_COMMAND_TOOL_CHAR_BUDGET, e não mais uma rodada de reescrita de descrição

A lógica geral, quando algo configurado não faz efeito, é sempre a mesma três: o arquivo não carregou, carregou de um lugar diferente do esperado, ou outro arquivo sobrescreveu

O /context, o /doctor, o /hooks e o /mcp existem exatamente pra você ver o que carregou, e a documentação de debug de configuração detalha cada um deles

O que aprendi mexendo em skills no dia a dia

Agora um pedaço de experiência própria, porque tem dois enganos aqui que eu já cometi na frente da câmera

No vídeo abaixo eu monto o ambiente com um plugin de skills e testo ele em cima de um projeto real

O primeiro aprendizado: depois de mexer no plugin (instalar ou alterar), eu recarrego os plugins antes de rodar o prompt

Se eu pulo esse passo, a skill não entra na jogada e parece que quebrou

Encerrar a sessão do Claude Code e abrir de novo dá no mesmo efeito, quando eu não quero pensar muito

E o teste que eu uso pra ter certeza é visual: eu olho a indicação de que as skills foram carregadas na saída do Claude Code

Se apareceu ali, o plugin está ativo naquela sessão, ponto

Se não apareceu, nem adianta debater description

Na instalação eu escolhi deixar valendo só no projeto de teste, pra manter o ambiente limpo e não misturar com o resto da máquina

O segundo aprendizado é o que mais gera falso positivo de "quebrou"

Quando eu pedi uma tarefa simples e bem descrita (um botão de exportar CSV só com os produtos filtrados), o Claude Code foi direto pra execução, sem me perguntar nada

E a ausência de perguntas parece prova de que a skill não foi acionada, né? Não é

A etapa de perguntas existe pra evitar suposição

Se não tem o que supor, o resto do processo é seguido do mesmo jeito

Pra confirmar isso eu forcei o cenário oposto: joguei um prompt vago (adicionar um sistema de autenticação ao projeto) e aí sim o Claude Code parou pra alinhar as escolhas antes de implementar

Mesma skill, comportamentos diferentes, por causa do prompt

E eu não confiei só na tela: abri o CSV gerado no editor e comparei as colunas exportadas com as colunas visíveis da tabela antes de dar a mudança como certa

faça o teste você também, é o tipo de conferência que muda sua confiança no setup

O fio que liga tudo isso ao tema do post é o seguinte: as edições que quebram gatilho quase nunca são as edições grandes

São as "melhorias"

Você enxuga a descrição, padroniza o nome da pasta, organiza o frontmatter, e no caminho tira justamente a palavra que fazia o casamento acontecer

Checklist rápido para revisar antes de salvar qualquer edição em skill

Salva esse bloco em algum lugar e passa o olho antes de dar o commit:

• a description ainda diz o que faz E quando usar, com os termos que você realmente digita no dia a dia
• nenhuma palavra-gatilho foi removida na reescrita (compare com a versão anterior, não com a memória)
• a description cabe em 1024 caracteres
• o nome da PASTA continua o mesmo, porque em skill pessoal e de projeto é dele que vem o comando
• o name segue as regras: minúsculas, números e hífens, até 64 caracteres, sem começar ou terminar com hífen e sem hífens consecutivos
• o frontmatter não ganhou um disable-model-invocation: true nem um user-invocable: false sem você querer
• não existe skillOverrides marcando essa skill como off ou user-invocable-only
• não existe outra skill com o mesmo nome em outro escopo brigando pela precedência
• se a skill precisa rodar em sessão remota ou pra outras pessoas, ela está commitada no .claude/skills/ do repositório, habilitada na conta ou distribuída em plugin, e não só no seu ~/.claude/skills/
• a listagem foi conferida depois de salvar, com o Claude ou com /context

Conclusão

Quando a skill do Claude Code não é acionada depois de uma edição, o culpado é quase sempre um de dois: a description, que perdeu os termos-gatilho, ou o escopo, seja pelo nome da pasta, seja por uma cópia de mesmo nome ganhando na precedência

O resto da lista (frontmatter, overrides, orçamento da listagem, ambiente remoto) resolve os casos que sobram

E o método de voltar um pedaço por vez, com um pedido de teste fixo, chega na resposta muito mais rápido que reescrever a skill inteira torcendo pra melhorar

Próximo passo concreto, agora, nessa ordem: roda /context e /doctor pra ver o que carregou de verdade, abre a description atual do lado da que funcionava e compara palavra por palavra

Só depois disso você edita

até o próximo post! 😀