Cuando instalas Claude Code, ya hay un conjunto de agentes: invisibles, listos, sin que tengas que crear nada.
Son los built-ins. Pero el sistema también permite que cualquier archivo
.md con el frontmatter adecuado
conviértete en un agente nuevo — un custom. El diagrama de abajo muestra la bifurcación: el director de orquesta
lee name e description, decide cuál de las dos ramas seguir y asigna el trabajo.
↑ El maestro no necesita saber si el agente es built-in o custom: lee name e description y decide. La bifurcación es interna al sistema.
💡 Concepto central
Para el director, built-in y custom son idénticos: ambos tienen nombre, descripción y herramientas.
La diferencia está en origen — los built-ins vienen con Claude Code; los customs los creas con un archivo
.md dentro de
.claude/agents/.
Contenido detallado
Qué son los built-ins
Claude Code registra cuatro agentes al instalarse. No aparecen como archivos en tu proyecto: están integrados en el binario. Los invocas por su nombre exacto o dejas que Claude los elija automáticamente.
Por qué conocer cada built-in
Cuando dejas que Claude elija, usa la description para decidir. Si no conoces los built-ins, no te das cuenta de que el elegido no es adecuado y creas un custom redundante innecesario.
Consejo: verifica /agents antes de crear cualquier custom.
Conceptos clave
- →Integrados en el binario — no son archivos, no aparecen en el proyecto ni requieren mantenimiento de tu parte.
- →Explorar es de solo lectura — por diseño, no tiene herramientas de escritura; es ideal para investigar de forma segura.
- →general-purpose ≠ personalizado — aunque le pases un "system prompt" al invocar general-purpose, no se convierte en un custom; es una persona temporal.
Cuál es la confusión
Mucha gente descubre que puede invocar el general-purpose con una instrucción adicional
— «actúa como un revisor de código crítico» — y crees que creaste un agente nuevo. No es así. Creaste una persona efímera:
existe solo en esa conversación, no tiene nombre propio en el sistema, no se puede invocar después y no aparece en el /agents.
Por qué importa la distinción
✅ Usa una persona efímera cuando
- ✓Es una tarea única, no repetitiva
- ✓No necesitas el agente mañana
- ✓El comportamiento varía en cada invocación
❌ No sustituye a custom cuando
- ✗Usas el mismo patrón todas las semanas
- ✗Otros del equipo necesitan invocar el mismo agente
- ✗Necesita herramientas restringidas o específicas
Conceptos clave
- →Persona efímera — existe solo en la conversación actual; desaparece cuando cierras la sesión.
- →Custom es persistente — vive en el archivo
.md, se puede versionar en Git y cualquier miembro del equipo puede usarlo. - →Regla práctica — si vas a repetirlo más de 3 veces, crea un custom.
Qué es un agente personalizado
Un agente custom es un archivo Markdown con frontmatter YAML en la primera línea. Guardado en
.claude/agents/
(proyecto) o ~/.claude/agents/ (global),
se registra automáticamente, sin instalar nada ni reiniciar.
Por qué funciona este formato
Claude registra al agente leyendo solo el frontmatter. El cuerpo del .md é o
system prompt del agente: solo se lee cuando se lo invoca. Esto permite tener un catálogo enorme de agentes
sin costo de tokens para el director: divulgación progresiva en acción.
Conceptos clave
- →Frontmatter obligatorio:
nameedescription. Lo demás es opcional. - →Alcance: agentes en
.claude/agents/del proyecto solo están disponibles allí; los globales están en~/.claude/agents/. - →Versionable: el archivo
.mdva a Git junto con el proyecto — todo el equipo usa la misma definición.
Qué es progressive disclosure aquí
El maestro no carga el cuerpo completo de cada agente en el contexto para decidir cuál usar.
Solo lee name e
description de todos los agentes disponibles —
un catálogo conciso. El system prompt completo (el cuerpo del .md) solo se
carga cuando el agente realmente se invoca.
Por qué esto importa
name + description de todos los agentes. Costo: mínimo..md se carga en la ventana del agente, no en la del maestro.Conceptos clave
- →Description como contrato: es lo único que determina cuándo se elige el agente. Una description vaga = invocación incorrecta.
- →Puedes tener 50 agentes sin pagar tokens de selección: el catálogo de names+descriptions es compacto.
- →Cuidado con las descripciones largas: la Ruta 2 enseñará a "recortar" para dejar solo el disparador esencial.
El modelo de costos
Cada token en el contexto del maestro cuesta dinero y atención. El modelo integrado/personalizado evita costos innecesarios: el maestro carga metadatos (name + description), no el system prompt completo.
✅ Con progressive disclosure
- ✓Maestro carga ~5 tokens por agente (name)
- ✓El system prompt solo entra en la ventana del agente
- ✓El contexto del maestro permanece limpio
- ✓Escala a decenas de agentes sin costo
❌ Sin separación (inline)
- ✗System prompt de cada agente en contexto
- ✗El contexto del maestro crece con cada turno
- ✗El costo se multiplica por el número de agentes
- ✗Menos espacio para el trabajo real
Por qué esto escala
20 agentes × 300 palabras cada uno = 6.000 palabras solo de «configuración» sin progressive disclosure. Con la separación: ~100 palabras de metadatos; las 300 de cada agente quedan guardadas hasta que se les llame.
Regla de oro: a description tiene menos de 2 líneas. El detalle va en el cuerpo del .md.
Conceptos clave
- →Metadatos ≠ comportamiento — description determina la selección; el cuerpo del .md determina la ejecución.
- →Separar responsabilidades — el maestro decide, el agente ejecuta, cada uno con su propio contexto.
- →El costo real es de atención, no solo de dinero: un contexto saturado produce respuestas peores.
Qué es /agents
Escribe /agents en Claude Code para abrir el panel
de agentes. Enumera todo: built-ins registrados por el sistema y customs encontrados en las carpetas
.claude/agents/ del proyecto y
~/.claude/agents/ global.
También es desde aquí que creas nuevos agentes con el asistente interactivo.
↑ Salida ilustrativa del /agents. Los built-ins aparecen primero; los customs muestran de qué carpeta vienen.
Por qué verificar antes de crear
Antes de escribir uno personalizado, abre el /agents
y lee las descripciones de las funciones integradas. En muchos casos —sobre todo en la búsqueda de código, la planificación y las tareas genéricas—
una función integrada ya hace lo que necesitas, sin configuración.
Flujo recomendado: /agents
→ lee las descriptions → si ninguna sirve, crea una personalizada. Nunca al revés.
Conceptos clave
- →/agents es el inventario: siempre la fuente de verdad sobre lo que está disponible en el contexto actual.
- →Alcance visible: /agents muestra los agentes del proyecto actual + los globales. En otro proyecto, la lista cambia.
- →Crear con el asistente: al presionar n en /agents, Claude te guía para completar el frontmatter — una buena puerta de entrada para tu primer custom.
Prompts listos para usar ahora
Copia cualquiera de estos prompts y pégalo en Claude Code para explorar los conceptos de este módulo en la práctica.
Resultado esperado: Claude usa el /agents internamente y te devuelve la lista con descriptions resumidas.
Claude comparará los built-ins disponibles con la tarea y recomendará el enfoque adecuado.
Bueno para experimentar con progressive disclosure: mira cómo el frontmatter por sí solo ya define el contrato.
Ejercicio
Accede al /agents en tu máquina y
cataloga los built-ins disponibles.
Para cada uno, escribe: nombre, una línea de description y un ejemplo de tarea para la que sería la opción correcta.
Cómo hacerlo
- Abre Claude Code y escribe
/agents. - Lee las descriptions de cada built-in (todavía no las custom).
- Para cada built-in, escribe: nombre | descripción resumida | ejemplo de tarea concreta.
- Identifica qué built-in usarías con más frecuencia en tu contexto de trabajo.
✅ Criterio de verificación
Completaste el ejercicio si puedes responder:
- →¿Cuál built-in es de solo lectura? (respuesta: Explore)
- →¿Cuál usar para crear un plan de refactorización? (respuesta: Plan)
- →¿Cuál usar cuando ningún otro encaja? (respuesta: general-purpose o claude)
Bono
Después de catalogar los built-ins, identifica una tarea de tu día que ningún built-in cubre bien. Anota el nombre que le darías al agente custom y una description de dos líneas. Vas a crear ese agente en la Trilha 2.
✅ Resumen del módulo
Próximo módulo:
1.5 — La pregunta decisiva. Cómo saber cuándo un subagente resuelve algo y cuándo lo complica.