🎯 The description is the trigger

New here? When you have several skills installed, the agent doesn't read each skill's full `skill.md` all the time — that would cost a lot in tokens (the unit that measures how much text was processed, covered in module 0.1). To decide which skill fits your request, it scans only the description — the short sentence at the top of the file, in the front matter.

This is module 3.2’s three-level loading in practice: level 1 is the name and description, and it’s ONLY with this level 1 that the agent decides whether to open the full skill (level 2). If the description doesn’t convince it, the skill isn’t even considered—no matter how good the steps inside are. It’s the label on a drawer: if it doesn’t accurately describe what’s inside, no one will open that drawer at the right time.

A vague description talks about the general domain; a good one describes the specific SITUATION that triggers it. Compare: “helps with documents” doesn’t give you anything useful for making a decision — almost any request “fits” that, or none really do. But “generates a contract PDF from a Word template when the user asks for ‘contract,’ ‘generate PDF,’ or ‘document template’” gives the agent real trigger words to compare with the request.

New here? There are two ways to trigger a skill. The first is to type the /nome-da-skill direct — like calling someone by their exact name, with no room for error, because you're pointing to the `name` in the front matter. The second is to write in plain English ("generate this month's report") and let the agent MATCH your intent to the description from an installed skill—like a receptionist who hears your request and knows which department to send you to.

Caption: the request in Portuguese comes in on the left; the agent compares it with the description of each installed skill (highlighted in the middle) and activates the best match — in this example, skill C.

Three traps keep recurring: (1) too generic—words that could describe any skill in the domain; (2) focused on “what the skill is” (“PDF tool”) instead of “when to use it” (“generates a contract PDF when the user says X”); (3) overlap—two skills with similar descriptions competing for the same request, which makes the agent choose incorrectly or hesitate between them.

# 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").

When two skills compete for the same situation — for example, "skill-relatorio-vendas" and "skill-relatorio-geral" with similar descriptions — the agent may get confused, choose the wrong one, or ask you too many questions to break the tie. The solution is to DIFFERENTIATE: each description should make clear the boundary that separates it from the other, not just what it does. Think of two neighboring storefront signs — if both say "sells food," customers won't know which is the pizzeria and which is the ice cream shop.

You don’t have to guess whether the description works — you can test it directly. Open a new session (without context from the previous conversation), write a natural-language request the way a real user would, and see whether the agent recognizes and activates the right skill. Repeat with 2-3 different sentences that describe the same intent — if any fail, the trigger is still too weak.

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.