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.
//
Busque em todas as páginas da documentação
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.
description, linguagem de disparo, falso positivo, falso negativo, cláusula "quando usar", especificidade.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.
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.
À 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.
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 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.
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.
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.
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.
Revisado por Chris St. John·Última atualização: 16 de jul. de 2026