Cuando escribes una solicitud, el maestro lee tu mensaje y, a continuación, lee las descriptions
de todos los agentes que existen. Hace una pregunta implícita: "¿alguno de estos textos coincide con lo que pidió el usuario?"
Si coincide, el agente se activa. Si no coincide —aunque el agente sea perfecto para la tarea— permanece inactivo.
La description es el único vínculo entre tu pedido y el especialista adecuado.
↑ El mismo mensaje del usuario, dos agentes con descriptions diferentes: resultados opuestos.
Contenido detallado
🔍 Por qué se activa la description
El maestro no tiene un catálogo de agentes memorizado. En cada turno, lee tu prompt y los campos
description de todos los agentes disponibles. La decisión de activar o no es una
correspondencia semántica entre lo que pediste y lo que describe la description —
no es un nombre, no es un emoji, no es un título.
⚙️ Cómo procesa el maestro
Envías: "revisa el código de pago antes del deploy".
El maestro recorre las descripciones de todos los agentes activos.
Si una description dice "después de cambios en pagos, úsalo de forma proactiva" — combina. Dispara.
Si la description solo dice "agente de revisión" — demasiado vaga para coincidir. Silencio.
El maestro lee la description en cada turno para decidir qué agente usar. Es el único texto que guía la selección automática.
Los agentes con descriptions vagas son invisibles para el maestro. Sin entender el mecanismo, creas agentes que nunca aparecen y no sabes por qué.
Correspondencia semántica · lectura por turno · description como algoritmo de enrutamiento.
⚖️ Débil × fuerte: qué las diferencia
Una description débil dice qué es el agente. Una descripción fuerte dice cuándo usar e para qué. La diferencia parece sutil, pero es la distancia entre un agente que nunca se activa y uno que se activa en el momento exacto.
❌ Descriptions débiles
- ▸
"Agente para revisão de código."
— vago, sin disparador, se activa para todo o para nada - ▸
"Helper de programação."
— tan amplio que compite con cualquier agente - ▸
"Especialista em segurança."
— título sin condición: el maestro no sabe cuándo - ▸
"Faz análises."
— una palabra que lo abarca todo y, por eso, no abarca nada
✅ Descriptions sólidas
- ▸
"Revisa diffs em auth/pagamentos. Use proactively após mudanças nessas áreas."
— dominio + condición + instrucción de cuándo - ▸
"Pesquisa na web e indexa fontes. Acione quando o usuário precisar de dados externos ou quiser verificar fatos."
— caso de uso claro, no competitivo - ▸
"Gera e revisa planos de implementação. Use proactively antes de qualquer tarefa de desenvolvimento grande."
— «antes de» define el momento exacto
La diferencia estructural: la descripción débil define la identidad; la fuerte describe la situación de uso.
Las descriptions débiles crean agentes que nunca se activan (subuso) o se activan para todo (sobreactivación). Una sólida es precisa.
Identidad vs. situación · activador condicional · «Use proactively» como instrucción de timing.
⏱️ "Use proactively" — el momento explícito
La frase Use proactively en description es una instrucción directa al maestro:
"no esperes a que el usuario lo pida explícitamente: actívalo cuando el contexto coincida". Sin ella, el director puede
dudar y no activar al agente incluso cuando el contexto es perfecto.
💡 Anatomía de una description con timing
Usa de forma proactiva después de cualquier cambio en auth, pagos o sesiones.
"Revisa el diff…" — la tarea en sí.
"Úsalo de forma proactiva después de…" — el momento explícito.
"auth, pagos, sesiones" — restringe el alcance.
⚡ Consejo práctico
Usa "Use proactively" solo cuando quieres una activación automática.
Para agentes que solo deben invocarse por nombre (@nome), omite la frase —
el maestro esperará entonces a que lo invoquen explícitamente, sin intervenir cuando no lo hayan llamado.
La instrucción "Use proactively" en la description autoriza al maestro a activar al agente sin una solicitud explícita del usuario.
Sin este patrón, los agentes valiosos quedan inactivos. Si lo aplicas en exceso, todo se dispara, lo cual no es deseable.
Proactivo vs. reactivo · "@nombre" para invocación manual · el momento como dimensión de la description.
🔥 Misfires: cuando el agente se activa por error
Hay dos tipos de misfire: más (se activa cuando no debería) y menos (no se activa cuando debería). Ambos tienen la misma causa: la description no describe el caso de uso con suficiente precisión.
🔊 Misfire A más — activación excesiva
- Causa: description demasiado amplia o «Use proactively» sin restricción de dominio.
- Síntoma: el agente aparece en solicitudes que no tienen nada que ver.
- Ejemplo: "Revisa código. Úsalo de forma proactiva." → se activa para cualquier mención al código.
- Corrección: añadir una restricción de dominio — "Revisa diffs en auth/pagos. Use proactively después de cambios en estas áreas."
🔇 Misfire A menos — activación insuficiente
- Causa: description demasiado específica, sin sinónimos o sin «Use proactively».
- Síntoma: el agente nunca aparece, aunque sea ideal para la tarea.
- Ejemplo: "Agente de revisión." → el maestro no relaciona la descripción con el pedido.
- Corrección: ampliar el vocabulario y agregar un trigger — "Revisa diffs. Úsalo de forma proactiva después de los cambios."
Cómo diagnosticar un misfire
Observa el comportamiento
¿El agente se activó cuando no debía o debería haberse activado y no apareció?
Lee la description actual
Pregunta: si yo fuera el director de orquesta, este texto me diría cuándo ¿usar ese agente?
Ajusta el activador o el dominio
Para agregar: añade una restricción. Para reducir: añade "Use proactively" y amplía el vocabulario.
Dos patrones de falla: el agente se activa demasiado (description amplia) o muy poco (description vaga/sin trigger).
Los misfires son la principal causa de desconfianza en el sistema. Reconocer el tipo agiliza la solución en segundos.
Exceso de activación frente a activación insuficiente · el dominio como filtro · diagnóstico iterativo.
💥 Colisión skill × agent: el caso plan-roaster
Skills (archivos en .claude/commands/) y los agents (archivos en
.claude/agents/) pueden entrar en conflicto cuando ambos tienen descripciones semánticas parecidas.
A veces, el maestro selecciona uno cuando el usuario quería el otro. El caso
plan-roaster ilustra ese problema y cómo resolverlo.
📌 El caso plan-roaster
❌ Antes: descripción que entraba en conflicto
description: Analiza y critica
planes de implementación.
tools: Read
Problema: "analiza planes" también coincide con la skill /plan → colisión.
✅ Después: description quirúrgica
description: Critica planes
de implementación listos,
buscando fallas y riesgos.
Usa después de un plan sea
generado, no durante.
tools: Read
Corrección: "después de generar un plan" distingue esto de /plan (que crea, no critica).
🧪 Cómo detectar colisiones
- →Pídele al director de orquesta: "lista los agentes y las skills que coinciden con 'crear un plan'".
- →Si dos aparecen con una semántica similar, uno de los dos necesita una description más específica.
- →Qué los diferencia: las skills son acciones que activa el usuario; los agents son trabajadores automáticos.
Hay una colisión cuando la descripción de un agent y la de una skill se superponen semánticamente: el agente coordinador elige uno, pero tú querías el otro.
A medida que crece el repertorio de agentes, las colisiones son inevitables sin disciplina en la description.
Superposición semántica · skill frente a agent · «después» como separador temporal del alcance.
🔄 Iterar: preguntar por qué no se activó
El maestro es tu aliado en el diagnóstico. Cuando un agente no se activa como esperas, la estrategia más rápida es preguntar directamente al maestro por qué no usó ese agente, y pedir que proponga una descripción corregida.
Por que o agente [nome] não disparou no meu último pedido?
Leia a description dele e explique o mismatch.
Depois proponha uma description corrigida.O agente [nome] disparou quando eu pedi "[pedido X]",
mas não queria isso. Leia a description e diga por que
combinou. Reescreva para evitar esse over-disparo.🔍 El ciclo de iteración
El flujo de diagnóstico: preguntarle al maestro sobre el mismatch, recibir una sugerencia, editar y probar.
Intentar adivinar el problema sin preguntarle al maestro es lento. Tiene acceso a la description y al contexto; aprovéchalo.
Diagnóstico asistido · ciclo corto · el maestro como detective de su propia selección.
🐛 Cerrar comillas en YAML: el bug real
El frontmatter de los agentes es YAML. YAML tiene reglas poco evidentes sobre comillas y saltos de línea. El error más común (e invisible) es una comillas sin cerrar o sangría incorrecta que hace que el parser corte la description por la mitad — el agente se carga, pero el activador queda truncado.
---
name: code-reviewer
description: "Revisa o diff após mudanças
em auth e pagamentos. Use proactively
após qualquer alteração nessas áreas.
tools: Read, Grep
---
# Code Reviewer
Revisa o diff do repositório atual...Error: comillas sin cerrar en " nunca cerradas. El parser YAML lee todo hasta la siguiente comilla (que no existe): la description queda truncada o rompe todo el frontmatter.
---
name: code-reviewer
description: Revisa o diff após mudanças
em auth e pagamentos. Use proactively
após qualquer alteração nessas áreas.
tools: Read, Grep
---
# Code Reviewer
Revisa o diff do repositório atual...Corrección: usar un bloque literal de YAML (sin comillas, con indentación coherente). La descripción se lee completa.
❌ Evitar
- • Comillas sin cerrar
- • Dos puntos sin comillas en medio de la frase
- • Sangría mixta (tabulación + espacio)
- • Líneas de continuación sin espacio inicial
✅ Hacer
- • Escalar de bloque: sin comillas, 2 espacios de sangría
- • Probar con
python -c "import yaml; yaml.safe_load(open('agent.md').read())" - • Una frase por línea en las continuaciones
🔍 Diagnóstico
- • ¿El agente se carga pero nunca se activa? Verifica el YAML.
- • Pídele al maestro: "lee el frontmatter de [agent.md] y valida el YAML".
Error silencioso de YAML que trunca la description: el agente existe, pero el disparador está roto.
Es el bug más difícil de detectar: el archivo es válido, el agente se carga, pero el comportamiento cambia sin aviso.
Block scalar YAML · análisis del frontmatter · validación antes de confiar en el disparador.
Prompts listos para usar ahora
Pega estos prompts directamente en el agente coordinador para diagnosticar y corregir las descripciones.
Por que o subagente [nome] não disparou nesse prompt?
Leia o arquivo .claude/agents/[nome].md, analise a
description e diga onde está o mismatch.
Depois reescreva a description para consertar.Liste todos os agentes e skills cujas descriptions
combinam com "[pedido X]". Se mais de um combinar,
aponte a colisão e sugira como diferenciar cada um.Leia o arquivo .claude/agents/[nome].md e valide o
frontmatter YAML. Há aspas não fechadas, dois pontos
no meio de strings sem aspas, ou indentação mista?
Se sim, corrija e mostre o frontmatter válido.Pantalla simulada: diagnosticando una description
Mira cómo se ve en la práctica el ciclo de diagnóstico: el usuario le pide al maestro que explique por qué el agente no se activó y recibe la description corregida.
Úsalo de forma proactiva después de cambios en la autenticación, los pagos o las sesiones.
↑ Recreación ilustrativa de la terminal. El maestro tiene acceso al archivo del agente y puede proponer la corrección directamente.
Ejercicio: reescribir una description débil
Dada la descripción de abajo, reescríbela para que el agente se active en el momento adecuado, sin activarse de más. Usa las tres dimensiones que aprendiste: qué, cuándo e dominio.
Description original (débil)
description: Agente que ayuda con los deploys.
tools: Bash, Read
Cómo hacerlo
- Imagina qué haría de útil ese agente en un deploy (p. ej., revisar variables de entorno, validar Docker, verificar migrations pendientes).
- Define cuándo ¿quieres que aparezca automáticamente — antes, durante o después del deploy?
- Restringe el dominio — debe activarse para cualquier ¿mención al código o solo para solicitudes explícitas de deploy?
- Escribe la description en 2–3 líneas, incluyendo "Use proactively" con la condición específica.
✅ Criterio de verificación
Tu description es buena cuando:
- →Un colega puede decir en 5 segundos cuándo ese agente se activa.
- →Ella no coincide con solicitudes genéricas como «ayúdame con el código» o «mira este archivo».
- →Ella sí coincide con solicitudes como «haz el deploy de la feature X» o «voy a subirlo a producción».
- →El YAML es válido: sin comillas sueltas y con una indentación de 2 espacios.
Ejemplo de una posible respuesta
description: Verifica los prerrequisitos de deploy:
variables de entorno, migraciones pendientes
y configuración de Docker. Úsalo de forma proactiva
cuando el usuario mencione deploy, subida
para producción o un push de una feature.
tools: Bash, Read
Observa: qué ("verifica los requisitos previos"), cuándo ("mencionar deploy/subida/push"), dominio específico.
✅ Resumen del módulo
Próximo módulo:
2.3 — El cuerpo es el cerebro. Qué va en el cuerpo del archivo .md y cómo define el comportamiento real del agente.