Claude ignorou sua skill? Como escrever a descrição para ela ser acionada

Fala aí, beleza? Você instalou a skill, ela está lá bonitinha na pasta, o pedido é EXATAMENTE do assunto dela… e o Claude simplesmente segue a vida como se nada existisse

A tentação nessa hora é culpar o modelo ("ah, ele não entendeu"), mas na prática o que acontece é bem mais chato e bem mais fácil de resolver

Agent Skills funcionam por divulgação progressiva: no início da sessão só o name e a description de cada skill entram no contexto, e o corpo do SKILL.md só é carregado depois que a skill é acionada

Traduzindo: aquele SKILL.md caprichado que você escreveu, com instruções, exemplos e regras, o Claude ainda NÃO leu na hora de decidir

O único texto que ele viu foi a sua descrição

Então quando a skill do Claude Code não é acionada, o lugar pra olhar primeiro é a description, não o prompt

Bora destrinchar os quatro sintomas mais comuns?

Sintoma 1: a descrição diz o que a skill faz, mas não quando usar

O cenário é esse: a skill aparece na listagem, o pedido é claramente da área dela, e nada acontece

Você acaba chamando na mão, ela funciona lindamente, e aí bate aquela sensação de que o roteamento automático é meio loteria

A causa:

Pré-inscrição Formação Claude Code

Domine o Claude Code do básico ao avançado

Você vai aprender a criar sistemas completos com Claude Code, sem precisar ser programador. Inscreva-se para ter acesso a um desconto de lançamento e bônus especiais!

Quero minha vaga

Descrição que é resumo, não gatilho

A documentação oficial de boas práticas de autoria é bem direta nisso: a description tem que incluir o que a skill faz E os gatilhos e contextos específicos de quando usá-la, porque é por ela que o modelo escolhe a skill certa entre várias disponíveis

Uma descrição tipo "ferramenta de análise de dados" não diz ao modelo NADA sobre quando aplicar

Ela descreve a skill pra um humano que já sabe o que ela faz

Tem outro detalhe fácil de errar: a doc pede description em terceira pessoa, porque esse texto é injetado no system prompt e pessoa gramatical inconsistente atrapalha a descoberta

Se você escreveu "eu ajudo você a…", já começou torto

A solução:

Reescrever colocando os termos que o usuário realmente digita

Não os termos bonitos do domínio, os termos que saem do seu teclado às onze da noite quando você quer resolver o problema

Pensa assim: a description não é a documentação da skill, é o texto de roteamento dela

Documentação vai no corpo do SKILL.md, que é carregado depois

Como prevenir:

Sempre que criar uma skill nova, escreva a descrição respondendo duas perguntas separadas: "o que ela faz?" e "em que situações o agente deve puxar isso?"

Se a segunda resposta não estiver no texto, a skill vai ficar de enfeite

Sintoma 2: a skill nem entra na lista (frontmatter ou pasta errados)

Aqui o sintoma é mais bruto: o /skills não mostra a skill, ou ela nunca aparece nem como candidata

Não adianta reescrever descrição nenhuma, porque o arquivo sequer foi carregado

A causa:

O SKILL.md exige frontmatter YAML com dois campos obrigatórios: name e description

E o name tem regras rígidas na especificação Agent Skills:

• só letras minúsculas, números e hifens
• máximo de 64 caracteres
• não pode começar nem terminar com hifen
• precisa bater EXATAMENTE com o nome da pasta, senão a skill não carrega

Esse último é o clássico

Você cria a pasta Revisor_PR e escreve name: revisor-pr no frontmatter, e pronto: skill fantasma

Tome cuidado também com os sinais de menor e maior: a spec orienta evitar < e > em qualquer ponto do frontmatter, porque eles podem injetar instruções não intencionais no system prompt

A solução:

Conferir o caminho antes de tudo

No Claude Code a skill vive em ~/.claude/skills/<nome>/SKILL.md (pessoal, vale em todos os projetos) ou em .claude/skills/<nome>/SKILL.md dentro do repositório (nível projeto, versionado junto com o time)

Se você trabalha em vários repos e vive recriando as mesmas skills, vale manter suas skills em um repositório reusável e distribuir a partir dali

Depois do caminho, confere os dois campos obrigatórios e o casamento pasta = name

Como prevenir:

Valide nome-da-pasta == name na hora da criação, não depois

É um erro de trinta segundos pra corrigir e de duas horas pra descobrir 😅

Sintoma 3: a descrição está boa, mas foi truncada antes de chegar ao modelo

Esse é o mais traiçoeiro de todos

A skill funciona perfeitamente quando você chama na mão, a descrição está redonda, com gatilho, terceira pessoa, tudo certinho… e mesmo assim ela nunca é escolhida sozinha

Costuma acontecer em setup com MUITAS skills instaladas

A causa:

Quando há muitas skills instaladas, o Claude Code encurta as descrições pra caber no orçamento de caracteres da listagem

E adivinha o que é cortado? Justamente o final do texto, onde a maioria das pessoas coloca a informação de roteamento

Isso não é teoria: existe issue aberta no repositório oficial descrevendo exatamente esse comportamento, a issue #64606 do anthropics/claude-code, com o título "Skill description budget silently truncates routing information, causing skill routing failures"

O problema é o "silently" aí no meio

Você não recebe aviso nenhum na cara, sua descrição simplesmente chega mutilada no system prompt

A solução:

Primeiro, medir

O comando /doctor dá uma estimativa do custo de contexto da listagem de skills e mostra os maiores contribuintes

Depois, olhar o log: quando a listagem estoura o orçamento, o Claude Code grava um aviso no log de debug, visível rodando com --debug

Se confirmar que é isso, dá pra aumentar o orçamento de caracteres da listagem pela variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET

Como prevenir:

Duas coisas simples

Coloque o gatilho no COMEÇO da description, não no fim (o fim é a primeira parte a sumir no corte)

E mantenha o conjunto de skills enxuto: cada skill instalada disputa espaço na mesma listagem com todas as outras

Sintoma 4: não é a descrição, é a skill que não foi descoberta

Sintoma: você reescreve a descrição, testa, reescreve de novo, muda palavra, muda ordem… e absolutamente nada no comportamento muda

Aí a pergunta certa não é "como melhoro o texto", é "essa skill está carregando?"

A causa:

Existem issues abertas no repositório oficial do Claude Code relatando skills em ~/.claude/skills/ e .claude/skills/ que não são descobertas ou carregadas, como as issues #11266 e #17417

E tem uma ainda mais confusa pro diagnóstico: a issue #14577 relata que o /skills pode mostrar "No skills found" mesmo com skills carregadas

Ou seja, nem todo caso de skill do Claude Code não é acionada é problema de descrição, e a própria listagem nem sempre é uma prova confiável do que está ativo

A solução:

Separar o diagnóstico ANTES de mexer no texto

Se a skill nem carrega, sua descrição é irrelevante, você vai passar a tarde polindo um texto que ninguém lê

Teste chamando a skill de forma explícita no prompt: se ela responde quando chamada pelo nome, o carregamento está ok e o problema é roteamento

Se nem chamada explicitamente ela entra, o problema é anterior

Como prevenir:

A ordem importa: confirma o carregamento primeiro, mexe no roteamento depois

Como reescrever a descrição para a skill ser escolhida

Beleza, e na prática, como fica esse texto?

A documentação do Claude Code, nos passos de verificação pra quando uma skill não é usada, manda checar se o campo description explica claramente QUANDO ela deve ser aplicada e se inclui palavras-chave relevantes

Esse é o alvo

1. Declare a capacidade em terceira pessoa

Comece pelo que a skill faz, de forma seca e verificável, sem "eu" e sem "você"

O erro comum deste passo: escrever em primeira pessoa ("Eu reviso seus PRs"), que é justamente o que a doc de boas práticas pede pra evitar, porque esse texto entra no system prompt

2. Liste os gatilhos e contextos concretos de quando aplicar

Situações reais, não categorias

O erro comum deste passo: gatilho genérico tipo "use quando o usuário precisar de ajuda com código", que casa com literalmente tudo e por isso não casa com nada

3. Inclua as palavras-chave que o usuário digita

As suas palavras, do dia a dia, inclusive as informais

O erro comum deste passo: jogar a keyword no fim da frase, que é a primeira parte a sumir se a listagem for truncada

4. Caiba no limite e sem < ou >

O campo description tem limite de 1.024 caracteres na especificação Agent Skills, e a spec orienta não usar os sinais de menor e maior em nenhum ponto do frontmatter

O erro comum deste passo: usar < e > pra marcar placeholder tipo nome de arquivo dentro da descrição

O resultado fica mais ou menos assim:

---
name: revisor-de-pr
description: Revisa diffs de pull request procurando bugs de correção, regressões e problemas de segurança. Use quando o usuário pedir revisão de PR, review de diff, "olha esse PR pra mim", checagem antes do merge ou análise das mudanças do branch atual.
---

Repara que a capacidade vem primeiro, os gatilhos vêm logo em seguida e as expressões coloquiais estão ali dentro, não escondidas no corpo do arquivo

5. Recarregue e teste com um pedido que use as palavras do gatilho

Teste implícito, sem citar a skill pelo nome: é assim que ela vai ser usada de verdade

O erro comum deste passo: testar chamando a skill explicitamente e concluir que "funcionou", quando o que você validou foi o corpo do SKILL.md, não o roteamento

O que aconteceu quando testei uma skill de design na prática

Pra sair da teoria, deixa eu contar o teste que eu fiz com uma skill de design

Antes de rodar, minha expectativa era clara: ou ela ativa sozinha, ou eu ia ter que forçar a ativação de alguma forma

Eu instalei em nível de projeto de propósito, justamente pra não deixar a skill ativa em contexto onde ela não tem nada que fazer (aliás, antes de escrever uma do zero, sempre vale garimpar skills do Claude prontas)

No Claude Code o /plugin gerencia plugins e marketplaces, e um plugin é o pacote que distribui uma ou mais skills, então esse é o caminho natural de distribuição quando a skill não é sua

No primeiro teste eu escrevi o pedido de forma implícita, sem citar a skill pelo nome, só descrevendo o protótipo clicável de app iOS que eu queria

E a skill carregou sozinha 🙂

Não precisei ativar na mão, e o resultado veio com 4 telas entregues

Mas aqui vai o alerta honesto: nem sempre é assim

Quando o agente interpreta o seu pedido como um projeto web comum, a skill não entra, e aí você precisa ser explícito no prompt

É o Sintoma 1 acontecendo ao vivo: o pedido não trouxe as palavras que casam com o gatilho

No teste de slides eu senti outra diferença: precisei detalhar MUITO mais as funcionalidades no prompt do que faria na ferramenta equivalente da Anthropic, porque lá certos comportamentos já vêm entendidos e na skill não

Um exemplo bobo: a navegação entre slides pelas setas do teclado, que eu tive que pedir no prompt

E olha só, mesmo pedindo, ao abrir o deck as setas não funcionaram de primeira 😅

Esse mesmo teste parou no meio: o agente devolveu perguntas sobre paleta e decisões visuais antes de continuar, e deixou 6 slides pendentes esperando confirmação

Eu atribuo isso ao projeto estar cru em dados, não a uma falha da skill

Em outro teste eu pedi explicitamente que ela sugerisse três direções visuais antes de produzir qualquer coisa, e ela devolveu as três opções pra eu escolher

E aí vem a amarração com o tema do post: esse comportamento de pausar, sugerir direções e pedir confirmação NÃO está na descrição

Esse comportamento mora no corpo do SKILL.md, que só é lido depois que a description fez o roteamento

Uma descrição boa não deixa a skill melhor, ela só garante que a skill boa seja chamada na hora certa

Um detalhe curioso que eu reparei: os artefatos gerados saíram com uma assinatura da própria skill no rodapé, tanto no slide quanto no player

Minha hipótese é que tem algo dentro da skill induzindo isso

Já vi outros pacotes de skills embutirem referências às empresas que os criaram, e existe reclamação da comunidade sobre esse viés, então fica o olho aberto no que você instala

Veja a skill em ação no vídeo

No vídeo abaixo eu mostro esse fluxo todo rodando, do pedido implícito que ativou a skill sozinha até o momento em que o agente parou e pediu confirmação

Conclusão

A description da sua skill não é a documentação dela

É a interface de roteamento: o único texto que o Claude tem em mãos no momento de decidir se aquela skill entra ou não na conversa, porque o corpo do SKILL.md só chega depois

Então, quando a skill do Claude Code não é acionada, o roteiro é esse:

abre o SKILL.md da skill ignorada e confere name, description e o casamento com o nome da pasta

roda o /doctor pra ver se a listagem está estourando o orçamento e comendo suas palavras-chave

e só então reescreve a description como capacidade + gatilhos, com os termos que você digita de verdade

Depois disso, se ainda não funcionar, aí sim a gente conversa sobre culpar o modelo 😀

até o próximo post!