Escrevendo uma Descrição de Skill Eficaz para o Claude Disparar
Uma Skill pode ter instruções impecáveis e ainda assim nunca ser usada.
Isso acontece quando seu campo description não faz seu trabalho: dizer ao Claude, com antecedência, o que a Skill faz e quando ela se aplica.
De tudo em um arquivo SKILL.md, a descrição carrega o maior peso, porque é a única parte que Claude avalia antes de decidir ler qualquer outra coisa.
Esta página foca inteiramente nesse campo: o que o faz funcionar, o que o faz falhar e como distinguir a diferença.
Resumo
- Ideia Central: A descrição de uma Skill é um sinal de correspondência, não documentação - Claude a compara com a tarefa atual para decidir se deve carregar a Skill.
- Por que Importa: Uma Skill com instruções excelentes e uma descrição vaga se comporta como nenhuma Skill, porque nunca é disparada.
- Conceitos Chave: campo
description, linguagem de disparo, falso positivo, falso negativo, cláusula "quando usar", especificidade. - Quando Usar: Recorra a isso sempre que uma Skill não disparar quando deveria, disparar quando não deveria, ou você estiver elaborando o frontmatter de uma Skill totalmente nova.
- Limitações / Trade-offs: Uma descrição muito ampla dispara em excesso; uma muito restrita dispara de menos. Não há uma única redação "correta", apenas um ajuste melhor ou pior para a gama de tarefas reais que você espera.
- Tópicos Relacionados: Frontmatter de SKILL.md, estruturando instruções passo a passo, erros comuns na descoberta de Skills, como Claude descobre e carrega Skills.
Fundamentos
O campo description de uma Skill faz um único trabalho: permite que Claude decida, sem ler o restante do arquivo, se essa Skill é relevante para a tarefa em questão.
Essa decisão ocorre em um contexto de todas as outras Skills disponíveis no mesmo contexto. Uma descrição vaga não arrisca apenas perder sua própria tarefa - arrisca perder para uma descrição mais precisa em uma Skill não relacionada, ou pior, corresponder a tarefas para as quais nunca foi destinada.
Uma descrição forte tem confiavelmente duas partes.
description: >-
Summarizes a customer support transcript into a structured ticket with
issue, steps taken, and resolution status. Use when the user pastes a
support conversation or asks to turn a conversation into a ticket.A primeira frase afirma o que a Skill faz, em termos de sua saída concreta - "um ticket estruturado com problema, passos tomados e status da resolução", não "ajuda com suporte".
A segunda frase afirma quando ela deve disparar, nomeando os sinais reais que uma tarefa real mostraria - um transcrito colado, uma frase específica como "transforme isso em um ticket".
Ambas as metades importam. Uma descrição com apenas a metade "o quê" diz a Claude o que a Skill produz, mas não quando uma tarefa a solicita. Uma descrição com apenas a metade "quando" pode disparar corretamente, mas deixa Claude adivinhando o que fazer de fato ao entrar na Skill.
Mecânicas e Interações
Claude avalia descrições da mesma forma que você avaliaria um pequeno anúncio de emprego: esta tarefa corresponde ao que está sendo descrito, de perto o suficiente para valer a pena uma análise mais detalhada?
Isso significa que as palavras que você escolhe importam mais do que poderiam em prosa comum. Duas direções de falha aparecem repetidamente.
Disparo insuficiente (Under-triggering) ocorre quando a descrição é muito restrita ou muito abstrata para corresponder à formulação real de uma solicitação. Uma descrição que diz "ajuda com suporte" raramente corresponde a uma solicitação formulada como "você pode transformar esta chamada em um ticket".
Disparo excessivo (Over-triggering) ocorre quando a descrição é ampla o suficiente para corresponder a tarefas para as quais nunca foi destinada. "Resume texto" como descrição dispara felizmente em um artigo de notícias, um documento legal e um transcrito de reunião, mesmo que as instruções da Skill tenham sido escritas de forma restrita para um deles.
Muito restrito: "Formata tickets de suporte."
Muito amplo: "Ajuda a organizar informações de conversas."
Equilibrado: "Resume um transcrito de suporte ao cliente em um ticket
estruturado. Use quando o usuário colar uma conversa de
suporte ou pedir para transformar uma conversa em um ticket."A versão equilibrada se ancora em uma forma de entrada específica (um transcrito de suporte), uma forma de saída específica (um ticket estruturado) e frases de gatilho específicas que um usuário real realmente digitaria ou colaria.
Uma verificação útil durante a elaboração: leia a descrição como se fosse o autor de outra Skill, competindo pela mesma tarefa. Sua redação venceria claramente contra uma Skill próxima e de nome semelhante? Se duas descrições na mesma biblioteca pudessem reivindicar plausivelmente uma determinada tarefa, essa ambiguidade precisa ser resolvida antes que qualquer Skill seja enviada.
A cláusula "Use quando..." merece atenção especial. Funciona melhor quando nomeia algo detectável na entrada ou solicitação real - um tipo de arquivo, um padrão de frase, uma situação descrita - em vez de um julgamento interno que apenas o autor da Skill reconheceria.
Considerações Avançadas e Aplicações
À medida que uma biblioteca de Skills cresce, as descrições param de ser avaliadas isoladamente e começam a competir umas com as outras. Uma descrição que era perfeitamente aceitável como a única Skill em uma pasta pode se tornar uma fonte de confusão quando cinco Skills relacionadas se sentam ao lado dela.
É aqui que a especificidade vale seu custo. Uma descrição ligeiramente mais longa e concreta que exclui claramente Skills vizinhas vale as palavras extras.
| Abordagem | Força | Fraqueza | Melhor Ajuste |
|---|---|---|---|
| Descrição curta e geral | Fácil de escrever, baixa manutenção | Propenso a disparo excessivo e insuficiente à medida que a biblioteca cresce | Uma Skill solo sem vizinhos próximos |
| Descrição de duas partes "o quê + quando" | Equilibra precisão com brevidade | Requer exemplos reais de frases de gatilho para escrever bem | A maioria das Skills de produção |
| Descrição longa e exaustiva com muitos exemplos de gatilho | Muito difícil de perder o gatilho pretendido | Parece inchado; ainda pode falhar se os exemplos não cobrirem a formulação real | Skills de alto risco com histórico de gatilhos perdidos |
Uma maneira prática de escrever a metade "quando" é coletar duas ou três solicitações reais que devem disparar a Skill e uma ou duas que deliberadamente não deveriam. Elabore a descrição e, em seguida, verifique-a contra todas elas. Se ela permitir a entrada de exemplos que não deveriam disparar, restrinja-a. Se ela perder um dos exemplos que deveriam disparar, afrouxe ou reformule-a.
Este processo é inerentemente iterativo. Poucas descrições estão corretas na primeira versão, e revisar uma descrição depois de observar que ela perdeu ou disparou em excesso em uma tarefa real é uma parte normal e esperada da construção de uma Skill - não um sinal de que algo deu errado anteriormente.
As descrições também envelhecem. Uma Skill originalmente definida para o fluxo de trabalho de uma equipe pode, com o tempo, ser solicitada a lidar com casos adjacentes que sua descrição nunca antecipou. Revisitar a descrição periodicamente, da mesma forma que você revisitaria qualquer peça de documentação, mantém o disparo preciso à medida que os padrões de uso reais mudam.
Conceitos Equivocados Comuns
- "O nome da Skill faz a maior parte do trabalho de descoberta." - A descrição carrega quase tudo. Um nome preciso com uma descrição vaga ainda não disparará de forma confiável.
- "Uma descrição mais longa é sempre uma descrição mais segura." - O comprimento não é a variável que importa; a especificidade é. Uma descrição longa, mas vaga, ainda pode disparar em excesso ou de menos.
- "Eu só preciso declarar o que a Skill faz - Claude descobrirá quando usá-la." - Sem um "quando" explícito, Claude tem que inferir as condições de disparo apenas do "o quê", o que é muito menos confiável do que declará-las diretamente.
- "Se uma Skill não está disparando, as instruções precisam de trabalho." - Um disparo perdido é quase sempre um problema de descrição. As instruções nunca são lidas se a descrição não corresponder primeiro.
- "Uma descrição mais ampla significa que a Skill será mais útil." - Linguagem ampla é mais provável de causar disparo excessivo em tarefas não relacionadas do que tornar a Skill "mais disponível" de uma boa maneira.
FAQs
Quais são as duas coisas que uma boa descrição de Skill precisa afirmar?
- O que a Skill realmente faz, em termos de sua saída concreta.
- Quando ela deve disparar, usando linguagem que corresponda a como uma solicitação real seria formulada.
Por que a descrição importa mais do que as instruções?
Porque Claude compara a descrição com uma nova tarefa antes mesmo de ler as instruções. Se a descrição não corresponder, as instruções nunca são avaliadas.
O que significa "under-triggering" (disparo insuficiente)?
- Uma Skill falha em ativar em uma tarefa que deveria lidar, geralmente porque a descrição é muito restrita ou abstrata para corresponder à formulação real da solicitação.
O que significa "over-triggering" (disparo excessivo)?
- Uma Skill ativa em tarefas para as quais não foi destinada, geralmente porque a descrição é ampla o suficiente para corresponder a solicitações não relacionadas.
Existe um padrão confiável para a metade "quando" de uma descrição?
O padrão "Use quando..." funciona bem porque nomeia explicitamente as condições de disparo em vez de deixá-las implícitas. Nomear um sinal concreto - uma frase, um tipo de arquivo, uma situação descrita - funciona melhor do que uma categoria abstrata.
Como testo se uma descrição está bem escrita?
- Colete algumas solicitações reais que devem disparar a Skill e algumas que não deveriam.
- Verifique a descrição rascunhada contra todas elas.
- Restrinja-a se um exemplo que não deveria disparar corresponder; afrouxe ou reformule-a se um exemplo que deveria disparar for perdido.
Uma descrição deve mencionar ferramentas específicas ou nomes de arquivos que a Skill usa internamente?
- Não. A descrição é sobre a tarefa e o gatilho, não sobre detalhes de implementação. Detalhes internos pertencem ao corpo das instruções, não à descrição.
O que acontece se duas Skills na mesma biblioteca tiverem descrições sobrepostas?
Claude pode escolher uma ou outra de forma inconsistente, ou a descrição mais específica pode vencer consistentemente, deixando a outra Skill efetivamente sem uso. Descrições sobrepostas devem ser resolvidas estreitando uma ou ambas.
É normal revisar uma descrição depois que a Skill já está em uso?
- Sim. Poucas descrições estão corretas na primeira versão, e revisar uma após observar um disparo perdido ou falso é uma etapa normal e esperada, não um sinal de falha de design.
Uma descrição pode ser muito longa?
O comprimento em si não é o problema, mas uma descrição preenchida com detalhes que não aprimoram o "o quê" ou o "quando" adiciona ruído sem adicionar precisão. Cada frase deve justificar seu lugar.
A descrição precisa usar as palavras exatas que um usuário digitaria?
- Não exatamente, mas deve ser próxima o suficiente em significado e formulação para que solicitações reais correspondam a ela de forma reconhecível. Linguagem excessivamente formal ou abstrata, mesmo que tecnicamente precisa, pode não capturar como as pessoas realmente pedem.
Relacionados
- Noções Básicas de Design e Empacotamento de Skills - onde o campo de descrição aparece pela primeira vez em um exemplo funcional.
- Como uma Skill se Junta: Da Ideia ao Pacote - o caminho completo que esta página detalha.
- Estruturando Instruções Passo a Passo Que Claude Pode Seguir Confiávelmente - o que acontece quando a descrição é bem-sucedida.
- Erros Comuns Que Tornam uma Skill Difícil de Encontrar ou Usar pelo Claude - uma lista mais ampla de falhas de disparo.
- Como Claude Descobre e Carrega Skills Automaticamente - o mecanismo para o qual o conselho desta página é escrito.
Versões de Stack: Escrito contra a linha de modelos Claude atual em ~junho de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (o padrão) e Claude Haiku 4.5. Nomes de modelos, preços e recursos de produtos mudam rapidamente - verifique os detalhes atuais em platform.claude.com/docs antes de confiar neles.