🎯 Como o Claude Escolhe uma Skill

Ao iniciar uma nova sessão com o Claude, o sistema executa uma etapa de inicialização que carrega os metadados de todas as skills disponíveis no ambiente. Esses metadados — essencialmente nome e início da descrição de cada skill — ficam disponíveis como referência que o Claude consulta a cada mensagem para determinar se alguma skill é relevante para o contexto atual. Esse processo acontece de forma transparente e automática, sem nenhuma ação do usuário.

O trigger automático é ativado quando o Claude identifica correspondência entre o que você está pedindo e o caso de uso declarado em alguma skill disponível. A correspondência não é exata — é semântica. O Claude não está procurando por palavras literais; ele está avaliando a intenção da sua mensagem contra a descrição da skill. É por isso que descrições ricas e específicas são tão críticas: elas aumentam a precisão da correspondência semântica.

Um erro comum de design é colocar as informações mais críticas de trigger no meio ou no fim do arquivo da skill, assumindo que o Claude lê o arquivo inteiramente antes de decidir. Na realidade, na fase de seleção o Claude vê apenas o nome e o início da descrição — não o corpo completo da skill. O corpo é carregado apenas depois que a skill é selecionada.

Isso tem implicações diretas e práticas para o design do frontmatter. Tudo que é essencial para a seleção correta — casos de uso principais, palavras-chave críticas, condições de ativação — deve estar visível nos primeiros parágrafos da descrição. Informações que só fazem sentido depois que a skill já foi selecionada podem ir no corpo do arquivo.

Colisão de trigger ocorre quando duas ou mais skills têm casos de uso sobrepostos na descrição — fazendo o Claude ficar em dúvida sobre qual selecionar. O sintoma mais comum é comportamento errático: às vezes a skill certa é selecionada, às vezes não. Em cenários de colisão, o Claude pode selecionar a skill errada, combinar instruções das duas, ou simplesmente não selecionar nenhuma — cada um desses comportamentos é indesejado.

O risco de colisão aumenta exponencialmente com o tamanho do inventário. Com 5 skills, é fácil garantir que não há sobreposição. Com 30, manter os domínios separados requer atenção deliberada. O único momento em que colisão é aceitável é quando você quer que o Claude selecione heuristicamente qual das duas skills similares é mais adequada ao contexto específico — e nesse caso, ambas as skills devem ter descrições que deixam clara a distinção entre elas.

Nome e descrição têm funções distintas e não intercambiáveis no sistema de skills. O nome serve ao invoke manual — quando você digita "/nome-da-skill" explicitamente — e como identificador único para evitar colisões. A descrição serve ao trigger automático — é o texto que o Claude analisa para decidir se invoca a skill baseado no contexto natural da conversa, sem que você precise invocar manualmente.

Essa separação tem uma consequência prática importante: você pode otimizar cada campo para sua função específica sem comprometer o outro. O nome pode ser técnico e conciso — ideal para invoke manual. A descrição pode (e deve) ser mais longa, rica em palavras-chave e casos de uso — ideal para trigger automático. Tentar fazer o nome servir como trigger automático resulta em ambos funcionando mal.

Uma skill nunca deve ir para uso produtivo sem passar por um protocolo mínimo de testes de trigger. O teste valida que a skill correta é selecionada nos cenários esperados e que não é selecionada em cenários onde deveria ser ignorada. Testar é a única forma de confirmar que o trigger funciona como você imaginou — não como você escreveu, mas como o Claude interpreta o que você escreveu.

O protocolo de teste em duas etapas cobre os dois modos de invocação: invoke direto (digitando "/nome-da-skill" explicitamente) valida que o nome está correto e que a skill executa conforme esperado. Prompt vago (descrevendo o cenário sem mencionar a skill) valida que o trigger automático funciona. Se um dos dois falha, há um problema diferente a diagnosticar.

Quando os testes revelam problemas — trigger não dispara, dispara errado, ou há colisão — o caminho de correção segue uma lógica específica. Não tente corrigir o comportamento ajustando o corpo da skill. O problema de trigger é sempre no frontmatter — nome ou descrição. O corpo é irrelevante para a seleção; ele só importa depois que a skill já foi selecionada.

As duas técnicas mais eficazes de correção são: adicionar especificidade (mais palavras-chave, mais casos de uso concretos, exemplos de prompts que deveriam ativar a skill) e adicionar exclusões ("Não usar quando o usuário estiver perguntando sobre X" ou "Esta skill é específica para Y, não para Z"). Exclusões são particularmente poderosas para resolver colisões sem precisar renomear nenhuma das skills envolvidas.