Como escrever a descrição de uma skill do Claude Code para ela ser acionada na hora certa

Fala aí, beleza? Se você escreveu uma skill caprichada e ela simplesmente nunca é acionada, o problema quase nunca está no conteúdo: está naquela única linha que você digitou com pressa no frontmatter

O campo description é o mecanismo principal de acionamento, é por ele que o Claude decide se aplica ou não a skill

O corpo do SKILL.md é implementação: o passo a passo, as regras, os exemplos, tudo que a skill deve executar depois que já foi escolhida. A description é roteamento, ela existe pra responder uma pergunta só: "essa é a skill certa pra esse pedido?"

E isso pesa mais do que parece, porque o Claude usa a description pra escolher a skill certa entre potencialmente mais de 100 skills disponíveis. É uma linha só, disputando atenção com todas as outras 😀

O que você precisa antes de escrever a description

Antes de mexer no texto, vale saber onde a coisa mora

No Claude Code, as skills ficam em dois lugares: ~/.claude/skills/ são as pessoais (valem em todos os seus projetos) e .claude/skills/ dentro do repositório são as do projeto, versionadas junto com o time

Cada skill é uma pasta com um SKILL.md dentro. Sem esse arquivo, não existe skill

~/.claude/skills/
└── formatador-py/
    └── SKILL.md

meu-projeto/
└── .claude/
    └── skills/
        └── padrao-api-interno/
            └── SKILL.md

E o frontmatter? Um SKILL.md válido exige apenas dois campos: name e description. Todo o resto é opcional

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

---
name: formatador-py
description: Formata e organiza imports de arquivos Python
---

O name tem regras próprias: limite de 64 caracteres, aceita apenas letras minúsculas, números e hífens, e não pode usar as palavras reservadas anthropic e claude. Tome cuidado com isso, é o tipo de detalhe que quebra a skill antes mesmo de você testar o texto da description

Além desses dois, o frontmatter aceita campos opcionais como disable-model-invocation e allowed-tools. Dá pra viver sem eles no começo, então foca no que importa agora

Como escrever a description passo a passo

Bora ver na prática? A ideia é montar a linha em camadas, e não escrever tudo de uma vez

1. Abra o SKILL.md e localize o frontmatter

É o bloco entre --- no topo do arquivo. É ali que o Claude olha, e só ali

---
name: analise-planilha
description: Analisa planilhas
---

# Análise de planilhas

Quando acionada, leia a planilha informada, valide os cabeçalhos...

O erro comum deste passo: escrever a explicação boa no corpo do arquivo e deixar a description como um resumo preguiçoso. O corpo só é lido depois que a skill já foi escolhida, então explicação linda lá embaixo não ajuda em nada no acionamento

2. Comece pelo QUE a skill faz, em terceira pessoa

A documentação oficial orienta escrever a description sempre em terceira pessoa, porque ela é injetada no system prompt e ponto de vista inconsistente atrapalha a descoberta

description: Analisa planilhas Excel e CSV, extrai métricas por coluna e gera um resumo estatístico

O erro comum deste passo: escrever "eu posso analisar suas planilhas" ou "você pode usar essa skill para analisar planilhas". Parece inofensivo, mas é justamente o que a doc manda evitar

3. Acrescente o QUANDO usar, com contexto e gatilho concreto

A orientação oficial é incluir na description tanto o QUE a skill faz quanto o QUANDO usá-la, com contextos e gatilhos específicos

description: Analisa planilhas Excel e CSV, extrai métricas por coluna e gera um resumo estatístico. Use quando o usuário enviar um arquivo .xlsx ou .csv, pedir análise de dados de planilha, relatório de vendas ou consolidação de abas

O erro comum deste passo: description genérica que não cita nenhuma situação. "Ajuda com dados" não é gatilho, é enfeite

4. Front-load: gatilhos e resumo nos primeiros caracteres

Como a description pode ser truncada, a orientação prática é colocar os termos de gatilho e o resumo da tarefa no INÍCIO

Pensa assim: se sobrar só o começo da linha, o começo precisa bastar

# ruim: o gatilho está no fim, é o primeiro pedaço a sumir
description: Esta skill foi criada pelo time de dados para padronizar as entregas internas e evitar retrabalho em relatórios recorrentes, e deve ser usada quando o usuário enviar um .xlsx

# bom: gatilho e tarefa logo de cara
description: Planilhas .xlsx e .csv: analisa colunas e gera resumo estatístico. Use ao receber arquivo de planilha, pedido de relatório de vendas ou consolidação de abas

5. Confira os limites antes de fechar

São dois limites que caem direto em cima do texto da sua description, e vale conhecer os dois

E tem ainda um outro mecanismo, que não é limite do seu texto individual: o orçamento agregado, somando todas as descrições instaladas. Esse eu explico mais pra frente, na seção de skill que não dispara

O erro comum deste passo: achar que "cabe em um dos limites" é suficiente. A especificação corta em 1.024, então esse é o teto real do seu texto

6. Reinicie a sessão pra valer

O Claude Code lê o frontmatter de cada SKILL.md encontrado nesses diretórios na inicialização da sessão, e carrega o conteúdo completo só quando a skill é acionada

O erro comum deste passo: editar a description e continuar testando na mesma sessão, achando que o texto novo já está valendo. Não está 🙂

Exemplos de description que acionam a skill na hora certa

A melhor forma de calibrar isso é ver o antes e o depois. Se liga

Skill de formatação de código

# antes
description: Formata código

# depois
description: Formata código Python e organiza imports no padrão do projeto. Use ao criar ou editar arquivos .py, antes de commit, ou quando o usuário pedir para formatar, padronizar ou limpar imports

A primeira versão não diz nem a linguagem. A segunda entrega linguagem, extensão de arquivo e três momentos concretos

Skill de análise de planilha

# antes
description: Eu ajudo você a entender seus dados de planilha

# depois
description: Planilhas .xlsx e .csv: valida cabeçalhos, calcula métricas por coluna e gera resumo. Use ao receber arquivo de planilha, pedido de relatório de vendas ou consolidação de abas

A primeira erra duas vezes: primeira pessoa ("eu ajudo") e segunda pessoa ("você"), exatamente o que a doc manda evitar

Skill de padrão interno do time

# antes
description: Padrões internos da equipe de backend

# depois
description: Padrão interno de endpoints REST: nomenclatura de rotas, formato de erro e paginação. Use ao criar ou revisar controllers, rotas, handlers de API ou ao abrir PR que toque em endpoints

Aqui o pulo do gato é citar os artefatos: controller, rota, handler, PR. São as palavras que aparecem no pedido real do dev

Skill de revisão de texto

# antes
description: Revisa textos com as regras da marca

# depois
description: Revisão editorial no guia de estilo da marca: tom, títulos e formatação. Use ao escrever ou revisar README, changelog, post de blog, release notes ou copy de landing page

Percebe o padrão? Verbo em terceira pessoa, objeto claro, e uma lista curta de situações que disparam

Se quiser uma referência de escrita, dá pra olhar o repositório público oficial de Agent Skills da Anthropic e a skill skill-creator, em skills/skill-creator/SKILL.md

Minha skill não dispara: causas e como resolver

Agora a parte que dói. O sintoma é sempre o mesmo ("instalei e nada acontece"), mas a causa varia

Sobre o truncamento vale um parágrafo à parte, porque mudou faz pouco tempo

O Claude Code aplica um limite próprio por description na listagem de skills, hoje com padrão de 1.536 caracteres (o parâmetro skillListingMaxDescChars). Esse limite era de 250 caracteres e foi elevado para 1.536 na versão 2.1.105, que também passou a exibir um aviso na inicialização quando há truncamento

Ou seja: se você escreveu a skill numa versão mais antiga, tem chance real de a sua description estar sendo cortada em 250 caracteres sem você nunca ter visto aviso nenhum. É o clássico "mas está tudo certo no arquivo", e está mesmo, só que o Claude nunca leu aquilo por inteiro

E tem o caso mais silencioso de todos, que não é limite do seu texto e sim do conjunto: existe um orçamento agregado para as descrições de skills, e acima de certo limite cumulativo as descrições deixam de entrar no system prompt. Aí o roteamento quebra mesmo com a skill instalada e escrita direitinho

A prevenção é chata mas funciona: description curta, gatilho na frente, e menos skills gigantes competindo pelo mesmo espaço. Se você mantém várias skills com textão cada uma, o problema não é uma delas, é o conjunto

Existe a variável de ambiente SLASH_COMMAND_TOOL_CHAR_BUDGET pra aumentar o orçamento total de caracteres das descrições de skills e comandos. Só que atenção: ela não remove o limite por description individual. Aumenta o bolo, não a fatia

Se você quer o roteiro de diagnóstico completo, eu destrinchei isso no post sobre quando o Claude ignora sua skill

O que eu vi na prática usando skills no Claude Code

Quando testei skills no Claude Code pra gravar um vídeo, a primeira coisa que ficou clara é a que mais confunde quem está começando: quem decide ativar a skill é a própria IA, com base naquele cabeçalho, e não um comando manual seu

A skill em si é um arquivo Markdown com estrutura fixa: nome, descrição do que ela faz e, no corpo, o detalhamento do que precisa ser executado quando ela for acionada. Simples assim

E o acionamento não é garantido. No meu teste, a primeira tentativa falhou: a ferramenta procurou a skill no escopo global, não encontrou, e só depois localizou a versão instalada no projeto

O que destravou foi citar explicitamente a skill no prompt. Depois disso ela apareceu como acionada na sessão e foi usada pra gerar o projeto

A diferença de resultado apareceu na comparação: gerei a mesma página com a skill de design acionada e sem ela. A estrutura saiu praticamente igual, porém a versão sem skill ficou bem menos polida, com ícones genéricos, emojis e uma paleta de cores mais bruta

A lição que fica pra description é direta: se você precisa citar a skill no prompt toda vez pra ela entrar, a description não está fazendo o trabalho dela. Citar no prompt é muleta de emergência, não é o funcionamento normal

Esse mesmo raciocínio vale pra qualquer skill de estilo visual, inclusive quando você escreve regras de breakpoint que o modelo segue: o corpo pode estar impecável, mas se a linha de roteamento não cita os gatilhos, o modelo nunca chega lá

No vídeo abaixo eu mostro esse fluxo inteiro, do acionamento que falha até a comparação de resultado

Conclusão

A régua de uma boa descrição de skill do Claude Code cabe em quatro pontos

• terceira pessoa, sempre (nada de "eu posso" ou "você pode")
• o QUE a skill faz mais o QUANDO usar, com contexto e gatilho concreto
• gatilhos e resumo no INÍCIO da linha, porque o texto pode ser truncado
• dentro dos limites: 1.024 caracteres da especificação, sem tags XML, e o cap de 1.536 caracteres da listagem do Claude Code

O próximo passo é bem prático: abre as skills que você já tem em ~/.claude/skills/ e em .claude/skills/, lê cada description em voz alta e pergunta se dá pra saber, só por ela, em que momento aquela skill deveria entrar

Ajustou? Reinicia a sessão e olha a inicialização, porque é ali que o aviso de truncamento aparece

Depois disso, o roteamento para de ser sorte e vira decisão sua 😀

até o próximo post!