Ya entiendes qué es un subagente y sabes escribir su .md y conoce la diferencia entre el proyecto y el ámbito global. Ahora viene la pregunta práctica: ¿cómo creo un agente de verdad, desde cero? El comando /agents es el asistente nativo de Claude Code: muestra lo que existe, abre el creador guiado y te permite ajustar el resultado. En este módulo crearás un agente completo (plan-roaster) y aprender exactamente cómo Claude decide a qué agente llamar.
Flujo del asistente /agents: del comando al agente activo en 3 pasos
Contenido detallado
🔍 El comando /agents — ver y crear
Tu panel de control de subagentes
O /agents es el punto de entrada para todo lo relacionado con agentes personalizados en Claude Code. Muestra la lista completa de agentes disponibles en el proyecto y a nivel global, y abre el asistente guiado de creación.
- • Enumera todos los agentes disponibles (del proyecto + globales)
- • Muestra dónde está guardado cada archivo .md
- • Abre el asistente interactivo de creación
- • Permite editar agentes existentes
- • Muestra la description, las tools y el modelo configurados
- • No crea el archivo manualmente (el wizard lo crea)
- • No ejecuta el agente directamente
- • No muestra los elementos built-in de Claude Code
- • No se sincroniza con otros proyectos
- • No define cuándo se activa Claude (eso lo define la description)
Al ejecutar /agents sin parámetros, Claude Code recorre los directorios .claude/agents/ del proyecto y del ámbito global, lee el frontmatter de cada uno .md y arma una lista con el nombre, la descripción truncada y la ubicación.
Antes de crear un agente nuevo, siempre lista los existentes: puede que ya tengas uno que cubra el caso de uso o que descubras nombres que coincidan con el que planeabas crear.
El proyecto prevalece sobre el global cuando hay un conflicto de nombres. El wizard de creación ya avisa si el nombre existe. La lista incluye los built-ins de Claude Code, separados de tus customs.
⚡ Generate-with-Claude × manual
Dos formas de completar el .md: cuándo usar cada una
Dentro del wizard, la opción Generate with Claude usa el modelo actual para redactar el archivo .md a partir de una descripción de alto nivel que escribes. Es el punto de partida más rápido, pero el output generado casi siempre necesita recortar la description.
Claude redacta el cuerpo, elige las herramientas y sugiere un modelo. Tú describes el objetivo en lenguaje natural. Resultado en segundos. Exige recortar la description para evitar que el texto sea demasiado largo.
Tú escribes el .md desde cero en un editor. Control total, sin sorpresas. Ideal cuando ya tienes una plantilla lista o estás iterando sobre un agente existente.
La elección entre los dos modos define la velocidad de creación vs. el control del resultado. Generar es ideal para el primer borrador; el modo manual es mejor para las iteraciones finas.
Los agentes generados automáticamente suelen tener descripciones verbosas que se activan en el momento equivocado. Saber cuándo recortarlas evita activaciones erróneas costosas.
Regla práctica — genera el borrador, abre el .md y reduce la descripción a un máximo de 2-3 frases con un activador explícito. El cuerpo puede ser detallado; la descripción debe ser precisa.
🧩 Opciones en el asistente de configuración: tools, model, color, memory
Las cuatro decisiones que definen el comportamiento del agente
El wizard te guía por cada campo, pero puedes dejarlo en blanco y editarlo después directamente en el .md. El campo tools es lo más crítico: los agentes con acceso irrestricto pueden realizar acciones inesperadas.
Lista de herramientas permitidas. Prefiere listas explícitas (ej.: ["Read","Bash","WebSearch"]). Omitirlo = hereda todas las herramientas del contexto principal.
Modelo que usar: haiku para tareas rápidas/baratas, sonnet para el equilibrio, opus para razonamiento complejo.
Color de la insignia del agente en la interfaz de Claude Code. Es puramente estético; sirve para distinguir agentes rápidamente en la lista de /agents.
Controla si el agente puede leer y escribir en la memoria persistente (allow / deny). En la mayoría de los casos, deny es más seguro: los agentes especialistas no necesitan memoria.
El wizard usa valores predeterminados conservadores: sin tools explícitas, sin modelo definido. En producción casi siempre querrás declarar tools e model para un comportamiento predecible.
Agente sin model el modelo definido hereda el modelo de Claude principal — puede cambiar de una sesión a otra según tu plan. Fijar el modelo garantiza costos y latencia predecibles.
Mínimo recomendado para producción: name, description (quirúrgica), tools (lista explícita), model. Color y memory son opcionales.
🔥 Caso plan-roaster: crear y recortar
De la idea al agente en funcionamiento: walkthrough completo
Cuando usas "Generate with Claude", el modelo genera una descripción larga y detallada. Parece buena, pero una descripción así activa el agente en contextos demasiado genéricos. El recorte es obligatorio.
/agents → Create → nombre: plan-roasterEl wizard pide el nombre. Usa kebab-case. Este agente revisará los planes de forma crítica.
Ej.: "agente que revisa planes de implementación, señala puntos ciegos, riesgos y mejores alternativas, como un ingeniero sénior escéptico"
.claude/agents/plan-roaster.md y recorta la descripciónReduce a 2 o 3 frases: el cuándo activa + el que hace. Elimina cualquier párrafo de contexto: eso va en el cuerpo.
@plan-roaster revise este planoSi se activa correctamente, comprueba que el output sea detallado. Si es genérico, amplía el cuerpo del .md.
Progressive disclosure aplicado a la description: Claude solo lee los primeros tokens de la description para decidir si activa el agente. Todo lo que viene después del activador principal rara vez influye en la activación.
Una description de 5 líneas con muchos contextos heterogéneos genera ambigüedad: Claude puede activar el agente incluso cuando no es lo ideal. 2-3 frases con un disparador claro son más precisas.
Fórmula para una description concisa: "Úsalo [cuándo exactamente]. [Qué hace en 1 frase]. [Opcional: ejemplos de activación]." El resto va en el cuerpo del .md, que el agente lee después de activarse.
🎯 Cuatro formas de invocar a un agente
Automático, proactivo, @nombre y --agent
Claude lee la description de todos los agentes disponibles en cada turno. Si tu prompt coincide con la description de un agente, se activa automáticamente, sin que tengas que pedirlo. Esto es modo automático. Pero puedes forzar otros modos.
Claude lee la descripción y activa el agente si el contexto coincide. Tú no haces nada: él decide. Depende de una descripción precisa.
La description incluye "Use proativamente quando..." — Claude verifica si debe activarlo aunque no lo pidas explícitamente, por ejemplo, después de hacer commits o al abrir un PR.
Escribes @plan-roaster revise isto. Activación garantizada, independientemente de la descripción. Más explícito, menos sorpresas. Ideal para probar un agente nuevo.
En la línea de comandos: claude --agent plan-roaster "revise o plano". Es útil en scripts y automatizaciones cuando no estás en modo interactivo.
Cuando dos agentes tienen descriptions que coinciden con el mismo prompt, Claude usa todo el contexto de la conversación para decidir cuál es más específico. Los agentes del proyecto tienen precedencia sobre los globales con el mismo nombre.
Si tienes un code-reviewer global y uno del proyecto; el del proyecto siempre prevalece. Esto permite personalizaciones por proyecto sin eliminar el global.
Orden de prioridad: 1) invocación @nome (forzado), 2) agente del proyecto (automático), 3) agente global (automático), 4) integrado. Los nombres únicos eliminan el problema de concurrencia.
🔧 Misfire y solución
Cuándo el agente se activa por error y cómo corregirlo
- • El agente se activa con prompts que no tienen nada que ver
- • Dos agentes se activan al mismo tiempo
- • El agente nunca se activa, incluso si lo pides
- • Se activa el agente equivocado (conflicto de descripciones)
- • Output genérico: no se leyó el contenido del .md
- • Ajusta la description: elimina el contexto innecesario
- • Renombra o separa las descriptions con distintos activadores
- • Agrega «Úsalo proactivamente cuando [frase exacta]»
- • Usa un prefijo en el nombre:
proj-code-reviewer - • Enriquece el cuerpo del .md con instrucciones detalladas
Pregúntale a Claude: "¿Por qué el agente plan-roaster ¿no se activó con mi último prompt?" — explicará qué description leyó y por qué no encajaba. Usa esa información para ajustar.
La description rara vez queda perfecta a la primera. El ciclo es: escribir → probar con más de 5 prompts variados → observar cuándo se activa y cuándo no → ajustar la description → repetir.
Los agentes de producción que se activan por error pueden consumir tokens innecesariamente o interferir en el flujo de trabajo. Iterar la descripción es el principal costo de mantenimiento de un agente.
Prueba con 5 prompts: 2 que deberían activar, 2 que no deberían y 1 caso límite. Si la tasa de aciertos es de 4/5 o más, la description está bien. Si es inferior, itera.
✂️ Recortando la description generada
El arte del corte preciso — progressive disclosure
Claude usa las descriptions de todos los agentes disponibles como parte del contexto de decisión en cada turno. Las descriptions largas consumen más tokens en esta ventana de selección, y la ambigüedad semántica en ellas provoca activaciones erróneas. La description óptima es la que supera la prueba de 5 prompts con el menor número de palabras.
"Este agente especializado en la revisión crítica de planes de implementación fue diseñado para analizar documentos de planificación técnica y estratégica, identificando vacíos, puntos ciegos, riesgos no considerados, dependencias ocultas y alternativas más eficientes. Actúa como un ingeniero sénior escéptico..."
"Úsalo de forma proactiva cuando el usuario presente un plan, una especificación o un documento de implementación para revisión. Revísalo críticamente como un ingeniero sénior escéptico: señala puntos ciegos, riesgos y alternativas."
La fórmula de 3 partes: (1) activador explícito con "Usa [cuando/proactivamente cuando]...", (2) qué hace en 1 frase activa, (3) opcionalmente, ejemplos de activadores como pista semántica.
Las descriptions que siguen esta fórmula tienen una tasa de misfire cercana a cero en pruebas empíricas. «Úsalo cuando» orienta a Claude hacia la intención correcta antes de cualquier ambigüedad semántica.
Plantilla: "Use proativamente quando [trigger]. [O que faz]. [Hint adicional opcional]." — 2-3 frases como máximo. Todo el contexto operativo va en el cuerpo de .md.
📄
Ejemplo real: plan-roaster.md
Archivo completo — descripción recortada, contenido enriquecido, herramientas mínimas
--- name: plan-roaster description: "Úsalo de forma proactiva cuando el usuario presente un plan, una especificación o un documento de implementación. Revísalo críticamente: señala puntos ciegos, riesgos y mejores alternativas." tools: [Read] model: claude-sonnet-4-5 color: red --- # Revisor de Planes (plan-roaster) Eres un ingeniero sénior escéptico. Tu función es revisar planes de implementación con escepticismo constructivo. Nunca los valides sin cuestionarlos. ## Protocolo de revisión 1. Lee el plan completo antes de comentar 2. Identifica las 3 principales brechas o riesgos 3. Para cada riesgo, sugiere una mitigación concreta 4. Señala las dependencias implícitas no declaradas 5. Cuestiona los supuestos de tiempo/costo 6. Concluye con un veredicto: Aprobar / Revisar / Rechazar ## Tono Directo, sin rodeos. Sin elogios innecesarios. Usa listas numeradas. Máximo 400 palabras en el output.
- • Description recortada a 3 frases con un disparador explícito
- •
tools: [Read]— mínimo necesario (solo lee, no escribe) - • Un cuerpo completo con un protocolo de 6 pasos: esto sí se lee después de activado
- • Tono definido explícitamente: evita respuestas genéricas
💬 Prompts listos
Copia y pega, y úsalo ahora
/agents → Create → nome: plan-roaster → Generate with Claude → "revisor crítico de planos como engenheiro sênior cético"
@plan-roaster revise o plano em docs/plan.md e me dê os 3 maiores riscos
Por que o agente plan-roaster não disparou quando eu disse "revise meu plano de migração"? O que estava na description que não combinou?
🖥️
Pantalla simulada: wizard /agents
Recreación ilustrativa — no es una captura de pantalla real
🏋️ Ejercicio: crea e invoca un agente por nombre
- 1.Abre Claude Code en tu proyecto y ejecuta
/agents— anota cuántos agentes ya existen. - 2.Crea un agente llamado
bug-hunterusando "Generate with Claude" con el objetivo: "agente que analiza código y encuentra posibles errores antes de un PR". - 3.Abre el
.mdgenerado y reduce la descripción a un máximo de 3 frases usando la fórmula del tema 7. - 4.Invoca por nombre:
@bug-hunter analise o arquivo main.py e me dê os 3 maiores riscos. - 5.Prueba 3 prompts que NO deberían activar al agente y confirma que no se active.
.claude/agents/bug-hunter.md existe en el proyecto
@bug-hunter devuelve un análisis estructurado con bugs enumerados
.md completado
📚 Resumen del módulo
/agents es el panel completo: lista, crea y edita agentes
Completaste la Ruta 2: ahora sabes crear agentes en la práctica. La Ruta 3 profundiza modelo, costo y orquestación: qué modelo elegir para cada tarea, cómo encadenar subagentes y medir el costo real de un sistema multiagente.