📏 Orçamento de Descrição

Existe um detalhe técnico sobre como o Claude Code processa as descrições das skills que a maioria dos usuários desconhece completamente: o modelo não lê a descrição inteira. Quando o sistema está montando o context window para uma interação, as descrições das skills disponíveis são incluídas de forma compactada. Descrições muito longas são truncadas — o restante simplesmente não chega ao modelo. Você pode ter escrito um parágrafo inteiro explicando quando e como usar a skill, mas se o gatilho está no terceiro parágrafo, o modelo nunca vai vê-lo.

Quando o modelo está decidindo qual skill usar, ele recebe um snapshot compactado dos metadados de cada skill disponível. Para a maioria das skills, isso significa apenas o nome e os primeiros tokens da descrição. O modelo toma a decisão de qual skill acionar com base nesse snapshot, não com base na leitura completa de cada skill. É por isso que a posição do gatilho na descrição não é uma preferência estética — é uma questão técnica direta de visibilidade.

O modelo vê apenas o início de cada descrição ao selecionar qual skill usar

A regra é simples e inegociável: a primeira frase da descrição deve ser o gatilho. Não uma introdução ao contexto, não uma explicação do que a skill faz em geral — o gatilho explícito de quando usar a skill. A primeira frase é o único fragmento que tem garantia de ser lido sempre. Tudo depois disso é conteúdo de suporte que pode ou não chegar ao modelo dependendo do tamanho da sua biblioteca.

Descrição enxuta não significa descrição curta — significa descrição densa. Cada palavra precisa carregar informação que diferencia a skill ou define seu uso. Palavras vagas como "ajuda a", "facilita o processo de", "permite que você" são desperdiçadores de tokens que ocupam espaço sem contribuir com nenhuma informação útil para a decisão de seleção do modelo. Cada palavra que você corta de uma descrição é um token que poderia ser usado para descrever um caso de uso adicional.

Você não precisa confiar apenas na teoria — é possível verificar empiricamente o que o Claude está recebendo das suas descrições. O método é simples: abra uma sessão nova e pergunte diretamente ao Claude o que ele sabe sobre suas skills disponíveis. A resposta revela o snapshot que ele recebeu, expondo qualquer truncamento ou vocabulário que chegou de forma diferente do que você escreveu. É o equivalente ao console.log para desenvolvedores — a inspeção direta do estado.

A diferença entre uma descrição que funciona e uma que falha raramente é dramática — é sutil. Por isso exemplos concretos são tão valiosos aqui. Ver o padrão errado e o padrão certo lado a lado cria um reconhecimento imediato que você vai aplicar instintivamente nas suas próprias skills. Os exemplos abaixo são baseados em padrões reais observados em bibliotecas de skills de usuários do Claude Code.