Mapa de la ruta
📋 El frontmatter completo
Config que determina quién eres
🎯 La descripción es el disparador
Una frase que activa al agente correcto
🧠 El cuerpo es el cerebro
Papel + pasos + salida + qué no hacer
🔐 Herramientas y permisos
tools: — solo lo necesario
📁 Proyecto × Global
Dónde vive define quién lo ve
🚀 Crear con /agents
Cómo elige y lanza Claude
Contenido detallado
📋 El frontmatter completo
El YAML entre los --- que configura todo antes de que Claude lea una línea del cuerpo. Cada campo, por qué existe y qué cambia si lo omites.
El bloque YAML delimitado por --- en la parte superior del archivo. Es la zona de configuración: Claude la lee antes de procesar el contenido.
Sin entender el frontmatter, todos los campos parecen magia. Entender la estructura permite distinguir lo que configura de lo que instruye.
Frontmatter = configuración; cuerpo = instrucción. Son zonas distintas con propósitos distintos.
El identificador único del agente. Aparece en el /agents, en el log de FleetView y permite invocarlo por nombre ("usa el security-reviewer").
Un nombre malo impide la invocación directa y llena el catálogo de ruido. Kebab-case descriptivo es la convención.
Kebab-case; sin espacios; el nombre = handle de invocación directa.
Lista YAML de las herramientas que el agente puede invocar: Bash, Read, Write, WebFetch, etc. Si se omite, obtiene acceso total, lo que rara vez es lo ideal.
Limitar las herramientas es la primera capa de seguridad. Un agente que solo puede leer no puede borrar nada.
Principio del mínimo privilegio; lista explícita > acceso total omitido.
Selecciona qué modelo de Claude ejecuta el agente: sonnet (predeterminado), haiku (rápido/barato), opus (profundo). Si lo omites, hereda el modelo del proceso principal.
Es la palanca del costo. Tareas mecánicas en haiku; análisis profundo en opus. Elegir conscientemente ahorra créditos.
Hereda si se omite; sonnet = opción segura predeterminada; haiku = baterías de tareas.
color define el color en FleetView; memory habilita notas persistentes; isolation: worktree se ejecuta en una rama de git aislada.
Los campos opcionales desbloquean casos de uso avanzados sin recargar el config básico. Tú decides cuándo crecer.
Opcional = progresivo; agrégalo cuando el caso lo requiera.
Sin name el archivo se ignora. Sin tools obtiene acceso total. Sin model hereda del padre. Sin description nunca se elige automáticamente.
Los valores predeterminados invisibles causan errores silenciosos. Saber qué activa cada omisión evita sorpresas en producción.
name obligatorio; description = enrutamiento automático; tools = seguridad.
🎯 La descripción es el disparador
El campo más influyente del agente. Una description bien redactada hace que Claude elija al agente adecuado automáticamente, sin que tengas que nombrarlo.
Cuando pides algo, Claude solo lee el name + description de todos los agentes disponibles y decide cuál usar sin ver el cuerpo.
Es el mecanismo central de enrutamiento. Entender cómo Claude decide qué agente llamar cambia la forma en que escribes la description.
Enrutamiento por description; el cuerpo solo se incluye cuando se activa el agente.
Una buena description incluye: (1) qué hace el agente, (2) cuándo usarlo y (3) ejemplos de activación, como la entrada de un diccionario de especialistas.
Es el texto más leído de tu agente: se lee cada vez que Claude decide. Una frase mal redactada = el agente nunca se invoca o siempre se invoca mal.
Qué hace + cuándo usarlo + ejemplos de activación.
Tres errores clásicos: (1) demasiado vaga: Claude nunca elige; (2) demasiado larga: desperdicia tokens del catálogo; (3) igual a general-purpose: el agente nunca supera la selección predeterminada.
Reconocer el error evita revisiones. Una descripción deficiente pasa inadvertida hasta que te das cuenta de que el agente nunca se activa.
Específico > genérico; conciso > extenso; diferenciado > copia del predeterminado.
Agregar en la description secciones explícitas "TRIGGER (cuándo activar)" y "SKIP (cuándo no activar)" — el patrón usado en los agents de producción.
Elimina falsos positivos. Claude entiende literalmente "no activar para X" y lo respeta: reduce las invocaciones innecesarias.
TRIGGER = señal verde; SKIP = señal roja explícita en la description.
El método: invocar al agente con escenarios reales, observar cuándo no se activa o se activa de forma incorrecta, perfeccionar la descripción y volver a probar: un ciclo corto.
Nadie acierta en el primer intento. El ciclo rápido de edición y prueba es la habilidad que distingue a los agentes funcionales de los que están eternamente "casi listos".
Ciclo editar → probar → ajustar; la retroalimentación es la señal, no la intuición.
Lectura y análisis de descriptions reales de agents del ecosistema Claude Code (claude-code-guide, general-purpose, Explore): qué funcionó y por qué.
Los ejemplos reales enseñan más que la teoría. Ver un patrón de producción calibra tus expectativas.
Coincidencia de patrones; leer los agentes existentes como ejercicio.
🧠 El cuerpo es el cerebro
El Markdown después del frontmatter. Aquí se definen el rol, los pasos, el formato de salida y lo que el agente nunca debe hacer: todo lo que determina la calidad del resultado.
La primera línea del cuerpo define el rol del agente: "Eres un especialista en X que hace Y". Esa frase ancla todo el comportamiento posterior.
Los agentes sin una declaración de función se desvían y se vuelven genéricos. La función es la guía que orienta cada decisión dentro de la tarea.
Papel = identidad; cuanto más específico, más coherente el output.
Lista numerada que define el protocolo: 1. Lee X 2. Identifica Y 3. Produce Z. El agente sigue la lista como una checklist interna.
Sin pasos, el agente interpreta de forma creativa; a veces bien, a veces no. Numerar los pasos hace que el comportamiento sea reproducible.
Reproducibilidad; cada paso = una acción verificable.
Una sección del cuerpo que indica exactamente el formato del informe: lista con viñetas, tabla, JSON, texto corrido, con un ejemplo mínimo si ayuda.
El maestro procesa la salida del agente. Un formato inesperado rompe la cadena. Especificar la salida es parte del contrato del agente.
Formato = contrato; el maestro es quien consume el output.
Sección "NO HAGAS" con prohibiciones explícitas: no borrar archivos, no hacer commits, no preguntarle al usuario, no inventar datos.
Las instrucciones negativas son más eficaces que las positivas para los guardrails. El agente recuerda más "nunca X" que "a veces no X".
Guardrail negativo = más fuerte; una lista de prohibiciones previene accidentes.
Puedes incluir contexto permanente en el cuerpo: rutas fijas de carpetas, convenciones del proyecto, listas de herramientas MCP disponibles.
El contexto en el cuerpo evita repetirlo en el prompt de invocación. El agente ya sabe dónde están las cosas antes de recibir la tarea.
Contexto permanente frente a contexto de invocación; el cuerpo es el briefing precargado.
El cuerpo mínimo incluye el rol, entre 3 y 5 pasos y el formato de salida. Un cuerpo completo agrega ejemplos, contexto y casos límite. Cuándo basta cada uno.
El perfeccionismo paraliza. Saber cuándo lo mínimo es suficiente y cuándo vale la pena invertir más es una habilidad práctica.
MVP del agente; iterar después de que funcione lo mínimo.
🔐 Herramientas y permisos
El campo tools determina lo que el agente puede y no puede hacer. El principio de mínimo privilegio aplicado — y cómo usar disallowed-tools para blindar.
Bash, Read, Write, Edit, WebFetch, WebSearch, Agent, Grep, LS — cada herramienta con su propósito y lo que permite hacer en el sistema.
No puedes dar permisos para algo que no conoces. Conocer el catálogo es el requisito previo para una configuración consciente.
Catálogo: Bash=ejecuta, Read=lee, Write=crea, Edit=modifica, Agent=subagente hijo.
Un agente de lectura necesita Bash (grep), Read y Grep — nada de Write o Edit. Define el scope según el tipo de tarea, no según "por si hace falta".
Los agentes con acceso excesivo causan daños accidentales. El menor privilegio hace que el agente sea predecible y auditable.
Los agentes de solo lectura = más seguros; Bash+Write = solo cuando sea necesario.
El campo disallowed-tools prohíbe herramientas específicas aunque el perfil principal las permita: una capa adicional de bloqueo explícito.
Cuando el agente hereda permisos de un perfil amplio, la lista de bloqueo es la única forma de excluir lo que no debe usar.
La blocklist complementa la allowlist; lo explícito sobrescribe lo heredado.
Las herramientas MCP (Model Context Protocol) amplían el catálogo: acceso a bases de datos, APIs externas y sistemas de archivos remotos; cada servidor MCP registrado se convierte en una herramienta.
MCP multiplica las capacidades del agente. Saber dar (o bloquear) acceso a un server MCP específico es una habilidad clave.
MCP server = conjunto de herramientas externas; nombre en tools: = registro.
Cómo usar el /agents para inspeccionar el perfil de herramientas de cada agente antes de ejecutarlo e identificar permisos excesivos.
La auditoría previa a la ejecución es el hábito que previene accidentes. «Déjalo correr y veamos qué pasa» es la receta para perder datos.
Revisar antes de ejecutar; /agents como herramienta de inspección.
Perfiles típicos: (1) Lector [Read, Bash(grep)] (2) Analista [Read, WebFetch, Bash] (3) Constructor [+Write, Edit] (4) Orquestador [+Agent]. Cada perfil con un uso objetivo.
Las plantillas aceleran la creación. En vez de inventar desde cero, eliges el perfil más parecido y lo ajustas.
4 perfiles base; ajústalos según el caso de uso.
📁 Proyecto × Global
Dónde está el archivo .md La ubicación determina quién lo ve: solo este repositorio o toda tu máquina. La regla es simple, la implicación es grande.
Proyecto: .claude/agents/ en la raíz del repositorio. Global: ~/.claude/agents/ en el home. Uno es local al repo; el otro está disponible en todos los proyectos de la máquina.
Ubicarlo en el lugar equivocado hace que el agente desaparezca (proyecto) o se filtre a contextos donde no debería existir (global).
.claude/agents/ = proyecto; ~/.claude/agents/ = global; el alcance determina la visibilidad.
Global es ideal para agentes de uso universal: revisores de código que no dependen del proyecto, investigadores y agentes de documentación personal.
Crear todo como global satura el catálogo de todos los proyectos. Saber distinguirlos evita confusiones al hacer la selección automática.
Global = independiente del proyecto; proyecto = especializado en el dominio del repo.
El proyecto es ideal para agentes que conocen el dominio específico del repositorio: estructura de carpetas, convenciones de nomenclatura, scripts locales.
Un agente de proyecto puede incluir en el cuerpo las rutas exactas del repo — context que un agente global nunca tendría.
El contexto específico del repo = ventaja del agente del proyecto.
Cuando hay dos agentes con el mismo nombre (uno del proyecto y otro global), prevalece el del proyecto —esto permite sobrescribir localmente el comportamiento global.
La sobrescritura es una función, no un error. Puedes adaptar un agente global a un proyecto específico sin modificar el agente global.
El proyecto sobrescribe el global; una sobrescritura intencional es una técnica válida.
Los agentes de proyecto van en git junto con el código: diff, blame, rollback. Los agentes globales quedan fuera del repo y necesitan una estrategia propia (dotfiles, symlinks).
Versionar el agente junto con el código garantiza que el equipo use la misma versión, sin divergencias silenciosas entre entornos.
Agente = código; versionar = trazabilidad; dotfiles para el ámbito global.
Convenciones para mantener legible el catálogo: prefijos por dominio (sec-, doc-, infra-), README.md en la carpeta agents y desuso explícito.
Con más de 20 agentes, el catálogo se vuelve un problema si no está organizado. Crear una estructura desde el inicio evita refactorizaciones futuras.
Prefijos + README + obsolescencia = catálogo sostenible.
🚀 Crear con /agents + cómo elige Claude
El comando /agents como interfaz de creación y gestión. Y el algoritmo de selección: por qué Claude llama a un agente y no a otro para la misma tarea.
El comando /agents es el panel de gestión: lista todos los agentes disponibles (integrados + personalizados), abre el asistente de creación y permite inspeccionar cualquier agente.
Es el punto de entrada práctico para todo lo que enseña la Ruta 2. Dominar el comando es dominar la interfaz de trabajo.
/agents = panel; lista + inspecciona + crea todo en un solo lugar.
Al crear mediante /agents, Claude guía un diálogo: pregunta el propósito, sugiere name/description/tools y genera el archivo; tú lo revisas y ajustas.
La creación guiada es más rápida que escribir desde cero. Pero entender el resultado te permite corregir lo que el asistente hizo mal.
Generación asistida + revisión humana = flujo de creación ideal.
Claude hace una comparación semántica entre la solicitud y las descriptions disponibles. Orden de preferencia: (1) invocación directa por nombre, (2) coincidencia sólida con la description, (3) general-purpose como alternativa.
Entender el algoritmo permite influir en la selección: escribir descripciones que superen a general-purpose en los casos que importan.
Directo > semántico > fallback; una description sólida vence a general-purpose.
Técnicas para diagnosticar una selección incorrecta: inspeccionar las descriptions de los agentes en competencia, identificar el solapamiento semántico, pedirle a Claude que explique su elección.
"Se llamó al agente equivocado" es el error más común de los catálogos que han crecido. Diagnosticar es más rápido que adivinar.
La superposición semántica = conflicto; una distinción clara = selección precisa.
Ejercicio completo: crear desde cero un agente de revisión de código (code-reviewer) — frontmatter, description con TRIGGER/SKIP, cuerpo con función+pasos+formato+lo que no debe hacer.
Es la síntesis de toda la Ruta 2. Después de este ejercicio, te llevarás un agente real funcionando en tu entorno.
De cero a funcional; todos los campos en armonía; prueba final.
T3 profundiza en el modelo y el costo (haiku vs opus para cada tipo de agente). T4 se expande a Codex y múltiples entornos. El Recorrido 2 es el núcleo que ambos amplifican.
El contexto sobre lo que viene después ayuda a priorizar: si el costo importa ahora, pasa a T3. Si el entorno es diferente, espera a T4.
T2 = crear; T3 = optimizar; T4 = expandir a otros entornos.