🎯 La descripción es el detonante

¿Eres nuevo aquí? Cuando tienes varias skills instaladas, el agente no lee el `skill.md` completo de cada una todo el tiempo: eso costaría muchos tokens (la unidad que mide cuánto texto se procesó, vista en el módulo 0.1). Lo que revisa para decidir qué skill coincide con tu pedido es solo la description — la frase breve que aparece en el front matter, al inicio del archivo.

Es exactamente cómo funciona en la práctica la carga en 3 niveles del módulo 3.2: el nivel 1 es nombre+descripción, y SOLO con este nivel 1 el agente decide si abre la skill completa (nivel 2). Si la descripción no convence, ni siquiera se considera la skill, sin importar lo bueno que sea el paso a paso que contiene. Es la etiqueta del cajón: si no describe bien lo que hay dentro, nadie abrirá ese cajón en el momento adecuado.

Una descripción vaga habla del área general; una buena habla de la SITUACIÓN concreta que la activa. Compara: "ayuda con documentos" no dice nada que ayude a decidir: casi cualquier solicitud "encaja" con eso, o ninguna encaja de verdad. En cambio, "genera un PDF de contrato a partir de un modelo de Word cuando el usuario pida 'contrato', 'generar PDF' o 'modelo de documento'" le da al agente palabras clave reales para comparar con la solicitud.

¿Eres nuevo aquí? Hay dos maneras de activar una skill. La primera es escribir el /nome-da-skill directo: como llamar a alguien por su nombre exacto, sin margen de error, porque estás apuntando al `name` del front matter. La segunda es escribir en español normal ("genera el informe del mes") y dejar que el agente HAGA COINCIDIR tu intención con la description de alguna skill instalada, como un recepcionista que escucha tu pedido y sabe a qué departamento enviarte.

Leyenda: el pedido en portugués entra por la izquierda; el agente lo compara con la descripción de cada skill instalada (resaltadas en el centro) y activa la que mejor coincide. En el ejemplo, la skill C.

Se repiten tres trampas: (1) demasiado genérica: palabras que sirven para cualquier skill del dominio; (2) centrada en «qué es la skill» («herramienta de PDF») en vez de «cuándo usarla» («genera un PDF de contrato cuando el usuario diga X»); (3) competencia: dos skills con descripciones parecidas que compiten por la misma solicitud, lo que hace que el agente elija mal o dude entre ambas.

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

Cuando dos skills compiten por la misma situación —por ejemplo, «skill-relatorio-vendas» y «skill-relatorio-geral» con descripciones parecidas—, el agente puede confundirse, elegir la incorrecta o hacerte demasiadas preguntas para desempatar. La solución es DIFERENCIAR: cada descripción debe dejar claro el límite que la separa de la otra, no solo lo que hace. Piensa en dos letreros de tiendas vecinas: si ambos dicen «vende comida», el cliente no sabe cuál es la pizzería y cuál la heladería.

No necesitas adivinar si la description funciona: puedes probarlo directamente. Abre una sesión nueva (sin contexto de la conversación anterior), escribe una solicitud en lenguaje natural como la escribiría un usuario real y fíjate si el agente reconoce y activa la skill correcta. Repítelo con 2-3 frases diferentes que describan la misma intención. Si alguna falla, el activador todavía es débil.

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.