🎯 A descrição é o gatilho

Novo aqui? Quando você tem várias skills instaladas, o agente não lê o `skill.md` completo de cada uma toda hora — isso custaria caro em tokens (a unidade que mede quanto texto foi processado, vista no módulo 0.1). O que ele varre, pra decidir qual skill combina com o seu pedido, é só a description — a frase curta que fica no front matter, no topo do arquivo.

É exatamente o carregamento em 3 níveis do módulo 3.2 na prática: nível 1 é nome+descrição, e é SÓ com esse nível 1 que o agente decide se abre a skill inteira (nível 2). Se a descrição não convencer, a skill nem é considerada — não importa quão bom seja o passo a passo lá dentro. É a etiqueta da gaveta: se ela não descreve bem o que tem dentro, ninguém vai abrir aquela gaveta na hora certa.

Uma descrição vaga fala do domínio geral; uma boa fala da SITUAÇÃO concreta que o dispara. Compare: "ajuda com documentos" não diz nada que ajude a decidir — quase qualquer pedido "combina" com isso, ou nenhum combina de verdade. Já "gera um PDF de contrato a partir de um modelo Word quando o usuário pedir 'contrato', 'gerar PDF' ou 'modelo de documento'" dá ao agente palavras-gatilho reais pra comparar com o pedido.

Novo aqui? Existem dois jeitos de disparar uma skill. O primeiro é digitar o /nome-da-skill direto — igual chamar alguém pelo nome exato, sem margem de erro, porque você está apontando pro `name` do front matter. O segundo é escrever em português normal ("gera o relatório do mês") e deixar o agente CASAR sua intenção com a description de alguma skill instalada — como um recepcionista que ouve seu pedido e sabe pra qual departamento te mandar.

Legenda: o pedido em português entra à esquerda; o agente compara com a description de cada skill instalada (destacadas no meio) e ativa a que casa melhor — no exemplo, a skill C.

Três armadilhas se repetem: (1) genérica demais — palavras que servem pra qualquer skill do domínio; (2) focada em "o que a skill é" ("ferramenta de PDF") em vez de "quando usá-la" ("gera PDF de contrato quando o usuário disser X"); (3) concorrência — duas skills com description parecida disputando o mesmo pedido, o que faz o agente escolher errado ou hesitar entre as duas.

# Ruim
description: Ajuda com relatórios da empresa.

# Melhor
description: Gera relatórios em PDF a partir de planilhas Excel.

# Boa
description: Gera o PDF do relatório mensal de vendas a partir da
  planilha vendas.xlsx quando o usuário pedir "relatório mensal",
  "fechamento do mês" ou "PDF de vendas". Não usar para relatórios
  de outro tipo (ver skill "relatorio-financeiro-anual").

Quando duas skills disputam a mesma situação — por exemplo, "skill-relatorio-vendas" e "skill-relatorio-geral" com descriptions parecidas — o agente pode confundir, escolher a errada, ou perguntar demais pra você desempatar. A saída é DIFERENCIAR: cada description deve deixar claro o limite que a separa da outra, não só o que ela faz. Pense em duas placas de loja vizinhas — se ambas dizem "vende comida", o cliente não sabe qual é a pizzaria e qual é a sorveteria.

Você não precisa adivinhar se a description funciona — dá pra testar direto. Abra uma sessão nova (sem contexto da conversa anterior), escreva um pedido em linguagem natural do jeito que um usuário real escreveria, e veja se o agente reconhece e ativa a skill certa. Repita com 2-3 frases diferentes que descrevem a mesma intenção — se alguma falhar, o gatilho ainda está fraco.

Sem executar nada ainda: olhando só as descriptions das skills
que você tem disponíveis agora, me diga qual skill você usaria
para cada um destes três pedidos, e por quê:
1) "<frase 1 que um usuário real diria>"
2) "<frase 2, mesma intenção, palavras diferentes>"
3) "<frase 3, mais indireta/informal>"
Se nenhuma skill combinar bem com algum pedido, me diga isso
também — não force um match.