Crear subagentes personalizados

Cree y utilice subagentes de IA especializados en Claude Code para flujos de trabajo específicos de tareas y una mejor gestión del contexto.

Los subagentes son asistentes de IA especializados que manejan tipos específicos de tareas. Utilice uno cuando una tarea secundaria inundaría su conversación principal con resultados de búsqueda, registros o contenidos de archivos que no volverá a consultar: el subagente realiza ese trabajo en su propio contexto y devuelve solo el resumen. Defina un subagente personalizado cuando siga generando el mismo tipo de trabajador con las mismas instrucciones.

Cada subagente se ejecuta en su propia ventana de contexto con un mensaje del sistema personalizado, acceso a herramientas específicas y permisos independientes. Cuando Claude encuentra una tarea que coincide con la descripción de un subagente, delega en ese subagente, que trabaja de forma independiente y devuelve resultados. Para ver el ahorro de contexto en la práctica, la visualización de la ventana de contexto muestra un recorrido por una sesión donde un subagente maneja la investigación en su propia ventana separada.

Los subagentes le ayudan a:

• Preservar contexto manteniendo la exploración e implementación fuera de su conversación principal
• Aplicar restricciones limitando qué herramientas puede usar un subagente
• Reutilizar configuraciones en proyectos con subagentes a nivel de usuario
• Especializar comportamiento con mensajes del sistema enfocados para dominios específicos
• Controlar costos enrutando tareas a modelos más rápidos y económicos como Haiku

Claude utiliza la descripción de cada subagente para decidir cuándo delegar tareas. Cuando crea un subagente, escriba una descripción clara para que Claude sepa cuándo usarlo.

Esas descripciones ocupan contexto, así que manténgalas breves. Cuando las descripciones combinadas de sus subagentes, excepto los integrados, superan 15.000 tokens, Claude Code muestra una advertencia al inicio con el recuento total de tokens. Recorte los campos description de sus subagentes y traslade los detalles al mensaje del sistema de cada subagente, que solo se carga cuando ese subagente se ejecuta.

Subagentes integrados

Claude Code incluye subagentes integrados que Claude utiliza automáticamente cuando es apropiado. Cada uno hereda los permisos de la conversación principal; la mayoría se ejecuta con un conjunto de herramientas restringido.

Explore y Plan omiten sus archivos CLAUDE.md y el estado de git de la sesión principal para mantener la investigación rápida y económica. Todos los demás subagentes integrados y subagentes personalizados cargan ambos. Para el desglose completo de lo que llega a un subagente, consulte qué se carga al iniciar.

Los subagentes integrados se registran por defecto en sesiones interactivas. Para restringirlos:

• Para bloquear un tipo integrado específico, agréguelo a permissions.deny como se muestra en Deshabilitar subagentes específicos.
• Para evitar que Claude delegue a cualquier subagente, deniegue la herramienta Agent en sí con permissions.deny.
• Para eliminar solo los subagentes integrados Explore y Plan, establezca CLAUDE_CODE_DISABLE_EXPLORE_PLAN_AGENTS=1. Claude lee y explora archivos directamente en lugar de delegarlos. Requiere Claude Code v2.1.198 o posterior.
• En modo no interactivo y el Agent SDK, establezca CLAUDE_AGENT_SDK_DISABLE_BUILTIN_AGENTS=1 para eliminar todos los tipos integrados y proporcionar solo los suyos.

Una llamada a la herramienta Agent que omite subagent_type falla con subagent_type is required cuando la sesión no tiene un subagente general-purpose al que recurrir.

Más allá de estos subagentes integrados, puede crear los suyos propios con mensajes personalizados, restricciones de herramientas, modos de permisos, hooks y skills. Las siguientes secciones muestran cómo comenzar y personalizar subagentes.

Inicio rápido: crear su primer subagente

Los subagentes son archivos Markdown con frontmatter YAML. Para crear uno, pida a Claude que lo escriba por usted, o escriba el archivo usted mismo.

A partir de v2.1.198, el comando /agents ya no abre el asistente de creación interactivo; ejecutarlo imprime un recordatorio para pedir a Claude o editar .claude/agents/ directamente. Los archivos de subagentes, los campos de frontmatter y las ubicaciones .claude/agents/ y ~/.claude/agents/ no cambian; solo se elimina el asistente de terminal.

Este tutorial crea un subagente a nivel de usuario que revisa código y sugiere mejoras.

Create a personal code-improver subagent in ~/.claude/agents/ that scans
files and suggests improvements for readability, performance, and best
practices. It should explain each issue, show the current code, and
provide an improved version. Make it read-only and have it use Sonnet.

---
name: code-improver
description: Scans files and suggests improvements for readability, performance, and best practices. Use after writing or modifying code.
tools: Read, Grep, Glob
model: sonnet
---

You are a code improvement specialist. For each issue you find, explain
the problem, show the current code, and provide an improved version.

Use the code-improver agent to suggest improvements in this project

Ahora tiene un subagente que puede usar en cualquier proyecto en su máquina para analizar bases de código y sugerir mejoras.

También puede escribir archivos de subagentes a mano, definirlos mediante banderas CLI, o distribuirlos a través de plugins. Las siguientes secciones cubren todas las opciones de configuración.

Configurar subagentes

La ubicación del archivo de un subagente determina quién tiene acceso a él, y su frontmatter determina qué puede hacer. Esta sección cubre dónde viven los archivos de subagentes y cada campo que soportan.

Elegir el alcance del subagente

Almacene archivos de subagentes en diferentes ubicaciones según el alcance. Cuando múltiples subagentes comparten el mismo nombre, Claude Code usa el de la ubicación de mayor prioridad.

Los subagentes de proyecto (.claude/agents/) son ideales para subagentes específicos de una base de código. Verifíquelos en control de versiones para que su equipo pueda usarlos y mejorarlos colaborativamente.

Los subagentes de proyecto se descubren caminando hacia arriba desde el directorio de trabajo actual, por lo que cada .claude/agents/ entre allí y la raíz del repositorio se escanea. A partir de v2.1.178, cuando más de uno de estos directorios anidados define el mismo name, Claude Code usa la definición más cercana al directorio de trabajo.

Cuando agrega un directorio con --add-dir o /add-dir, Claude Code también carga su carpeta .claude/agents/, junto con sus subagentes de proyecto. Consulte Directorios adicionales para ver qué otros tipos de configuración se cargan desde --add-dir. Para compartir subagentes entre proyectos sin --add-dir, use ~/.claude/agents/ o un plugin.

Los subagentes de usuario (~/.claude/agents/) son subagentes personales disponibles en todos sus proyectos.

Claude Code escanea .claude/agents/ y ~/.claude/agents/ recursivamente, por lo que puede organizar definiciones en subcarpetas como agents/review/ o agents/research/. La ruta del subdirectorio no afecta cómo se identifica o invoca un subagente, porque la identidad proviene solo del campo name del frontmatter.

Mantenga los valores de name únicos en todo el árbol: si dos archivos bajo el mismo directorio .claude/agents/, incluyendo sus subcarpetas, declaran el mismo nombre, Claude Code carga solo uno de ellos, elegido por orden de lectura del sistema de archivos en lugar de una precedencia documentada. En directorios de proyecto anidados, la definición más cercana al directorio de trabajo gana, como se describe arriba. El chequeo de configuración /doctor reporta archivos en el mismo directorio que comparten un nombre y propone renombrar o eliminar todos excepto uno. Antes de v2.1.205, /doctor abría una pantalla de diagnósticos que listaba duplicados y mostraba qué definición estaba activa.

Los directorios agents/ de plugins también se escanean recursivamente. A diferencia de los alcances de proyecto y usuario, una subcarpeta dentro del directorio agents/ de un plugin se convierte en parte del identificador con alcance: un archivo en agents/review/security.md en el plugin my-plugin se registra como my-plugin:review:security.

Los subagentes definidos por CLI se pasan como JSON al lanzar Claude Code. Existen solo para esa sesión y no se guardan en disco, lo que los hace útiles para pruebas rápidas o scripts de automatización. Puede definir múltiples subagentes en una única llamada --agents:

claude --agents '{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
},
"debugger": {
"description": "Debugging specialist for errors and test failures.",
"prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
}
}'

claude --agents @'
{
"code-reviewer": {
"description": "Expert code reviewer. Use proactively after code changes.",
"prompt": "You are a senior code reviewer. Focus on code quality, security, and best practices.",
"tools": ["Read", "Grep", "Glob", "Bash"],
"model": "sonnet"
},
"debugger": {
"description": "Debugging specialist for errors and test failures.",
"prompt": "You are an expert debugger. Analyze errors, identify root causes, and provide fixes."
}
}
'@

La bandera --agents acepta JSON con un campo prompt más estos campos de frontmatter: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, skills, initialPrompt, memory, effort, background, e isolation. Use prompt para el mensaje del sistema, equivalente al cuerpo markdown en subagentes basados en archivos. Cada clave de nivel superior en el JSON es el nombre del agente. No comience un nombre con -.

Para lo que Claude Code hace con un valor que no puede cargar, y las banderas y variable de entorno que omiten esa verificación, consulte Configuración de --agents inválida.

Los subagentes administrados son implementados por administradores de la organización. Coloque archivos markdown en .claude/agents/ dentro del directorio de configuración administrada, usando el mismo formato de frontmatter que los subagentes de proyecto y usuario. Las definiciones administradas tienen precedencia sobre los subagentes de proyecto y usuario con el mismo nombre.

Los subagentes de plugin provienen de plugins que ha instalado. Se cargan automáticamente junto a sus subagentes personalizados y aparecen en la lista de @-mention bajo su nombre con alcance. Consulte la referencia de componentes de plugin para obtener detalles sobre la creación de subagentes de plugin.

Las definiciones de subagentes de cualquiera de estos alcances también están disponibles para equipos de agentes: al generar un compañero de equipo, puede hacer referencia a un tipo de subagente, y Claude Code aplica partes de esa definición al compañero. Consulte equipos de agentes para ver qué partes se aplican en cada modo de visualización.

Escribir archivos de subagentes

Los archivos de subagentes usan frontmatter YAML para configuración, seguido del mensaje del sistema en Markdown:

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. When invoked, analyze the code and provide
specific, actionable feedback on quality, security, and best practices.

El frontmatter define los metadatos y la configuración del subagente. El cuerpo se convierte en el mensaje del sistema que guía el comportamiento del subagente. Los subagentes reciben solo este mensaje del sistema más detalles básicos del entorno como el directorio de trabajo, no el mensaje del sistema de Claude Code.

En modo no interactivo, pase --append-subagent-system-prompt para anexar su texto al final del mensaje del sistema de cada subagente, incluyendo subagentes anidados, aparte de un subagente bifurcado, que reutiliza el mensaje del sistema de la conversación. Requiere Claude Code v2.1.205 o posterior. Si su texto es demasiado largo para pasar en la línea de comandos, guárdelo en un archivo y pase la ruta con --append-subagent-system-prompt-file en su lugar. La bandera de archivo requiere Claude Code v2.1.261 o posterior.

Un subagente comienza en el directorio de trabajo actual de la conversación principal. Dentro de un subagente, los comandos cd no persisten entre llamadas de herramientas Bash o PowerShell y no afectan el directorio de trabajo de la conversación principal. Para dar al subagente una copia aislada del repositorio en su lugar, establezca isolation: worktree.

Un subagente con isolation: worktree ejecuta sus comandos Bash y PowerShell dentro de su worktree. Un comando cuyo directorio de trabajo se resuelve a su checkout principal en su lugar, por ejemplo porque el directorio worktree fue eliminado mientras el subagente estaba ejecutándose, falla con un error. Antes de v2.1.203, tal comando podría ejecutarse en el checkout principal.

Esta verificación de directorio de trabajo cubre todo el repositorio que contiene el directorio desde el que lanzó Claude Code. Cuando su sesión se ejecuta en un worktree vinculado de su propiedad, la verificación también cubre el checkout principal desde el que ese worktree está vinculado. Antes de v2.1.210, la verificación cubría solo el directorio de lanzamiento en sí. Un comando cuyo directorio de trabajo se resolvía en otro lugar en el mismo repositorio, como la raíz del repositorio cuando lanzó Claude Code desde un subdirectorio de monorepo, se ejecutaba allí en lugar de fallar.

Para comandos Bash, Claude Code también verifica el comando en sí de dos maneras:

• Bloquea un comando que redirige git al checkout principal.
• Se niega a un comando cuando no puede verificar desde el texto del comando que cualquier git que el comando ejecute permanece dentro del worktree, por ejemplo cuando el nombre del comando se calcula en tiempo de ejecución.

Los vectores de redirección y las reglas de forma se enumeran en Cómo Claude Code aplica el aislamiento. Los comandos PowerShell obtienen solo la verificación de directorio de trabajo.

Los comandos Monitor pasan por las mismas verificaciones de directorio de trabajo y contenido de comando que los comandos Bash.

Cuando la conversación principal en sí se ejecuta aislada en un worktree, Claude Code aplica las mismas verificaciones a la sesión y a cada subagente que genera, incluyendo subagentes sin isolation: worktree; consulte Cómo Claude Code aplica el aislamiento.

Campos de frontmatter soportados

Los siguientes campos se pueden usar en el frontmatter YAML. Solo name y description son requeridos.

Escriba cacheTtl dentro del mapa experimental, no en el nivel superior del frontmatter.

---
name: repo-auditor
description: Audits a large repository and reports what it finds
experimental:
  cacheTtl: 1h
---

Archivos de subagente que Claude Code omite

Claude Code omite un archivo en un directorio agents de proyecto, usuario o administrado, o en uno bajo un directorio que agrega con --add-dir, sin reportarlo en la sesión, cuando el frontmatter tiene alguno de estos problemas:

• Sin name: Claude Code trata el archivo como documentación guardada junto a sus agentes.
• Un --- de apertura que no es la primera línea del archivo: Claude Code lee el archivo como si no tuviera frontmatter y lo trata como documentación.
• Un name que comienza con - o contiene :: Claude Code omite el archivo y escribe un error en el registro de depuración. Consulte la fila name en la tabla anterior.
• Un name pero sin description: Claude Code omite el archivo y escribe la razón en el registro de depuración.
• YAML que no se analiza: Claude Code no lee campos del archivo, lo omite y escribe el error de análisis en el registro de depuración.

Para ver el registro de depuración, ejecute Claude Code con --debug.

Un subagente de plugin cuyo frontmatter no tiene name o no se analiza aún se carga, bajo su nombre de archivo.

Verificar un directorio `agents` antes de una sesión

Para encontrar archivos en un directorio agents cuyo frontmatter no se analiza, ejecute claude plugin validate contra el directorio, por ejemplo .claude/agents o ~/.claude/agents. Claude Code verifica solo el directorio que nombra, y no marca un archivo cuyo frontmatter se analiza pero no tiene name. Requiere Claude Code v2.1.233 o posterior.

Elegir un modelo

El campo model controla qué modelo usa el subagente:

• Alias de modelo: use uno de los alias disponibles: sonnet, opus, haiku, o fable
• ID de modelo completo: use un ID de modelo completo como claude-opus-5 o claude-sonnet-5. Acepta los mismos valores que la bandera --model
• inherit: use el mismo modelo que la conversación principal

Cuando Claude invoca un subagente, también puede pasar un parámetro model para esa invocación específica. Claude Code resuelve el modelo del subagente en este orden:

1. El parámetro model por invocación
2. El frontmatter model de la definición del subagente, donde inherit selecciona el modelo de la conversación principal
3. La variable de entorno CLAUDE_CODE_SUBAGENT_MODEL, cuando la establece en un alias de modelo o ID de modelo
4. El modelo de la conversación principal

Establecer CLAUDE_CODE_SUBAGENT_MODEL por sí solo no cambia el modelo en el que se ejecutan los subagentes integrados Explore y Plan. Para cambiarlo, consulte Ejecutar cada subagente en un modelo.

Antes de v2.1.251, CLAUDE_CODE_SUBAGENT_MODEL venía primero en este orden y anulaba tanto el parámetro por invocación como el frontmatter, incluyendo model: inherit.

Establecer la variable en inherit es lo mismo que dejarla sin establecer. Antes de v2.1.196, ese valor forzaba subagentes al modelo de la conversación principal e ignoraba las otras fuentes.

Claude Code verifica el parámetro por invocación, frontmatter y valores de variable de entorno contra la lista de permitidos availableModels de su organización. Para un valor bloqueado, sustituye otro modelo:

• Cuando el valor bloqueado es un alias de familia como opus, Claude Code ejecuta el subagente en la versión más nueva de esa familia que la lista de permitidos permite, siguiendo las mismas reglas de sustitución y alcance de proveedor que /model. Antes de v2.1.222, Claude Code ejecutaba el subagente en el modelo heredado para un alias de familia bloqueado también.
• Para cualquier otro valor bloqueado, en proveedores donde esa sustitución no opera, o cuando la lista de permitidos no permite ninguna versión de la familia, Claude Code ejecuta el subagente en el modelo heredado en su lugar. Si establece CLAUDE_CODE_SUBAGENT_MODEL, Claude Code intenta ese modelo primero, bajo estas mismas reglas.

En sesiones interactivas, Claude Code muestra una advertencia nombrando el modelo solicitado y el modelo en el que se ejecuta el subagente, para cualquiera de las sustituciones.

Para verificar qué modelo está ejecutando un subagente, ejecute /tasks. Claude Code nombra el modelo en la fila del subagente, y agrega el nivel de esfuerzo cuando la definición del subagente, o la skill de la que se bifurcó, establece effort. Requiere Claude Code v2.1.242 o posterior.

Un parámetro model por invocación también se aplica cuando el subagente se reanuda o se le envía un mensaje de seguimiento, por lo que el subagente permanece en ese modelo. Antes de v2.1.211, reanudar eliminaba el valor por invocación y el subagente revertía al campo model de su definición o, sin uno, al modelo de la conversación principal.

A partir de v2.1.198, los subagentes también heredan la configuración de pensamiento extendido de la conversación principal: si el pensamiento está activado en su sesión, está activado para el subagente, y si está desactivado, permanece desactivado. No hay una configuración de pensamiento por subagente. Antes de v2.1.198, los subagentes se ejecutaban con pensamiento extendido deshabilitado independientemente de la configuración de la conversación principal.

Ejecutar cada subagente en un modelo

CLAUDE_CODE_SUBAGENT_MODEL es un valor predeterminado, por lo que la definición de un subagente o un modelo que Claude pasa aún tiene precedencia sobre él. Para aplicar un modelo a cada subagente, compañero de equipo, y agente de flujo de trabajo, también establezca CLAUDE_CODE_SUBAGENT_MODEL_FORCE en 1. Requiere Claude Code v2.1.257 o posterior.

• Si establece ambas variables, los subagentes se ejecutan en el modelo en CLAUDE_CODE_SUBAGENT_MODEL.
• Si establece solo CLAUDE_CODE_SUBAGENT_MODEL_FORCE, los subagentes se ejecutan en el modelo de la conversación principal.

Por ejemplo, para ejecutar cada subagente en Haiku, establezca ambas variables en el bloque env de un archivo de configuración:

{
  "env": {
    "CLAUDE_CODE_SUBAGENT_MODEL": "haiku",
    "CLAUDE_CODE_SUBAGENT_MODEL_FORCE": "1"
  }
}

Para verificar que la configuración surtió efecto, ejecute /tasks mientras se ejecuta un subagente. La fila del subagente muestra el modelo en el que se ejecuta.

Mientras CLAUDE_CODE_SUBAGENT_MODEL_FORCE está activado, Claude Code ignora el campo model de cada definición de subagente, incluyendo los subagentes integrados Explore y Plan, y Claude no puede pasar un modelo cuando inicia un subagente. Dos tipos de subagente aún se ejecutan en el modelo de la conversación principal:

• Una bifurcación
• Una skill que se ejecuta en un subagente con model: inherit

Cuando establece solo CLAUDE_CODE_SUBAGENT_MODEL_FORCE, el subagente integrado Explore mantiene su límite de modelo.

Controlar capacidades de subagentes

Puede controlar qué pueden hacer los subagentes a través del acceso a herramientas, modos de permisos y reglas condicionales.

Herramientas disponibles

Los subagentes heredan las herramientas integradas y herramientas MCP disponibles en la conversación principal, reducidas por dos filtros: el primero elimina una lista corta de herramientas de cada subagente, y el segundo reduce el conjunto de herramientas integradas para subagentes que se ejecutan en segundo plano, que es el predeterminado. En macOS, Linux y WSL, un subagente también puede recibir las herramientas Glob y Grep cuando la conversación principal no las tiene, como se describe en Comportamiento de la herramienta Glob. Las bifurcaciones omiten ambos filtros y reciben el grupo de herramientas exacto de la conversación principal. El primer filtro elimina estas herramientas, incluso cuando se enumeran en el campo tools:

• Agent, cuando el subagente está en el límite de profundidad; en una bifurcación la herramienta permanece listada pero devuelve un error en lugar de generar
• AskUserQuestion
• EndConversation, que solo puede terminar la conversación principal; consulte Comportamiento de la herramienta EndConversation
• EnterPlanMode
• ExitPlanMode, a menos que el permissionMode del subagente sea plan
• ScheduleWakeup
• TaskOutput
• WaitForMcpServers
• Workflow

El segundo filtro se aplica a subagentes que se ejecutan en segundo plano. Aparte de Agent y ExitPlanMode, que siguen las condiciones del primer filtro dondequiera que se ejecute el subagente, un subagente en segundo plano mantiene todas las herramientas MCP pero solo estas herramientas integradas: Read, Grep, Glob, Bash, PowerShell, Edit, Write, NotebookEdit, WebFetch, WebSearch, TodoWrite, Skill, ToolSearch, EnterWorktree, ExitWorktree, Monitor, TaskStop, SendMessage, y Artifact. Claude Code elimina todas las otras herramientas integradas de un subagente en segundo plano, ya sean heredadas o listadas en el campo tools, por lo que la misma definición puede resolver a diferentes herramientas en primer plano y en segundo plano. La eliminación no reporta error a menos que deje la lista tools resolviendo a nada.

ListAgents sigue estos filtros como cualquier herramienta integrada: un subagente en primer plano la hereda en sesiones donde la mensajería entre sesiones está habilitada, y un subagente en segundo plano no la mantiene.

Los compañeros de equipo en equipos de agentes además mantienen las herramientas de tareas y herramientas cron: TaskCreate, TaskGet, TaskList, TaskUpdate, CronCreate, CronDelete, y CronList.

En una sesión sin las herramientas Task, Claude Code no proporciona las herramientas de tareas a los subagentes tampoco, incluso cuando el subagente ejecuta un modelo diferente. Un compañero en proceso sigue su sesión de la misma manera, mientras que un compañero en su propio panel dividido se ejecuta como un proceso Claude Code separado, por lo que su propio modelo decide.

Para restringir herramientas, use el campo tools como una lista blanca o el campo disallowedTools como una lista negra. Este ejemplo usa tools para permitir solo Read, Grep, Glob y Bash. El subagente no puede editar archivos, escribir archivos, o usar ninguna herramienta MCP:

---
name: safe-researcher
description: Research agent with restricted capabilities
tools: Read, Grep, Glob, Bash
---

Este ejemplo usa disallowedTools para heredar el grupo de herramientas del subagente excepto Write y Edit. El subagente mantiene Bash, herramientas MCP y el resto de su grupo:

---
name: no-writes
description: Inherits the available tools except file writes
disallowedTools: Write, Edit
---

Si ambos se establecen, disallowedTools se aplica primero, luego tools se resuelve contra el grupo restante. Una herramienta listada en ambos se elimina.

Cuando nada en la lista tools se resuelve a una herramienta, por ejemplo porque cada entrada está mal escrita o nombra una herramienta que no está disponible para subagentes, Claude Code generalmente se niega a lanzar el subagente y la herramienta Agent devuelve un error nombrando las entradas no resueltas; consulte Agent sería generado con cero herramientas para el mensaje y cómo corregir cada entrada. Antes de v2.1.208, ese subagente se lanzaba sin herramientas y podría devolver un resultado vacío o confuso.

Ambos campos aceptan patrones a nivel de servidor MCP además de nombres de herramientas exactos: mcp__<server> o mcp__<server>__* otorga o elimina todas las herramientas del servidor nombrado. En disallowedTools, mcp__* también elimina todas las herramientas MCP de cualquier servidor. Este ejemplo elimina todas las herramientas del servidor MCP github mientras mantiene herramientas de otros servidores y las herramientas integradas en su grupo:

---
name: local-only
description: Inherits every tool except those from the github MCP server
disallowedTools: mcp__github
---

Una entrada disallowedTools con un especificador, como Bash(git push *), aún elimina la herramienta completa del subagente, no solo los comandos coincidentes. Para mantener Bash y bloquear comandos específicos, agregue una regla de negación de Bash como Bash(git push *) a permissions.deny en su configuración. La regla se aplica a la conversación principal y a los subagentes.

Restringir qué subagentes pueden ser generados

Cuando un agente se ejecuta como el hilo principal con claude --agent, puede generar subagentes usando la herramienta Agent. Para restringir qué tipos de subagentes puede generar, use la sintaxis Agent(agent_type) en el campo tools.

---
name: coordinator
description: Coordinates work across specialized agents
tools: Agent(worker, researcher), Read, Bash
---

Esta es una lista blanca: solo los subagentes worker y researcher pueden ser generados. Si el agente intenta generar cualquier otro tipo, la solicitud falla y el agente solo ve los tipos permitidos en su mensaje. Para bloquear agentes específicos mientras se permiten todos los demás, use permissions.deny en su lugar.

Para permitir generar cualquier subagente sin restricciones, use Agent sin paréntesis:

tools: Agent, Read, Bash

Si Agent se omite completamente de la lista tools, el agente no puede generar ningún subagente con la herramienta Agent.

La sintaxis de lista blanca Agent(agent_type) se aplica solo a un agente que se ejecuta como el hilo principal con claude --agent. En una definición de subagente, listar Agent en tools permite que ese subagente genere subagentes de su propio mientras el límite de profundidad lo permite, pero cualquier lista de tipos dentro de los paréntesis se ignora.

Alcance de servidores MCP a un subagente

Use el campo mcpServers para dar a un subagente acceso a servidores MCP que no están disponibles en la conversación principal. Los servidores en línea definidos aquí se conectan cuando el subagente comienza, sujetos a la regla de confianza para la carpeta del archivo del agente, y se desconectan cuando termina. Las referencias de cadena comparten la conexión de la sesión principal.

Cada entrada en la lista es una definición de servidor en línea o una cadena que hace referencia a un servidor MCP ya configurado en su sesión:

---
name: browser-tester
description: Tests features in a real browser using Playwright
mcpServers:
  # Inline definition: scoped to this subagent only
  - playwright:
      type: stdio
      command: npx
      args: ["-y", "@playwright/mcp@latest"]
  # Reference by name: reuses an already-configured server
  - github
---

Use the Playwright tools to navigate, screenshot, and interact with pages.

Las definiciones en línea usan el mismo esquema que las entradas del servidor .mcp.json, con clave del nombre del servidor, y soportan los tipos stdio, http, sse y ws.

Para mantener un servidor MCP fuera de la conversación principal por completo y evitar que sus descripciones de herramientas consuman contexto allí, defínalo en línea aquí en lugar de en .mcp.json. El subagente obtiene las herramientas; la conversación principal no.

Claude Code carga un servidor en línea desde un archivo de agente en el directorio .claude/agents/ de su proyecto, o en el directorio .claude/agents/ de un directorio agregado con --add-dir, solo después de que confíe en la carpeta de la que provino el archivo del agente. Antes de v2.1.238, Claude Code cargaba estos servidores sin verificar confianza.

• Confianza que no cuenta: la confianza de una carpeta principal, y la confianza automática que una sesión -p o SDK obtiene para hooks en archivos de configuración
• Hasta entonces: Claude Code omite cada servidor en línea en ese archivo de agente y escribe la clave exacta projects["<path>"].hasTrustDialogAccepted para ~/.claude.json en el registro de depuración
• Directorios --add-dir: un directorio fuera del repositorio del espacio de trabajo de confianza necesita su propia entrada de confianza, ya que sus archivos .claude/agents/ no heredan la confianza del espacio de trabajo

Claude Code carga dos tipos de servidor sin verificar confianza para la carpeta de la que provino el archivo del agente:

• Un nombre que hace referencia a un servidor que ya configuró
• Un servidor en línea en un archivo de agente desde ~/.claude/agents/, en uno que pasa con --agents o la opción agents del SDK, o en uno que la configuración administrada proporciona

A partir de v2.1.153, las restricciones de MCP que se aplican a la sesión principal también cubren servidores declarados en frontmatter de subagentes:

• --strict-mcp-config y --bare
• Configuración de MCP administrada empresarial
• Políticas allowedMcpServers y deniedMcpServers

Cuando uno de estos bloquea un servidor, Claude Code lo omite y muestra una advertencia nombrando los servidores bloqueados.

Las restricciones de configuración administrada se aplican a cada subagente independientemente de cómo se defina. --strict-mcp-config no filtra servidores que pase en línea a través de --agents o la opción agents del SDK, ya que esa es entrada explícita del llamador.

Modos de permiso

Establezca permissionMode para elegir el modo de permiso en el que se ejecuta un subagente. Use los valores de configuración de los modos, por lo que el modo Manual es default. Si lo deja sin establecer, el subagente hereda el modo de la conversación principal, que comienza como modo auto en planes Pro, Max y Team a menos que su configuración u su organización lo cambien.

El modo de permiso de la conversación principal decide si Claude Code usa el valor que establece:

• Cuando la conversación principal está en bypassPermissions, acceptEdits, o modo auto, el subagente se ejecuta en ese mismo modo y Claude Code ignora el permissionMode que establece. Bajo modo auto, el clasificador evalúa las llamadas de herramientas del subagente con las reglas de bloqueo y permiso de la conversación principal.
• Cuando la conversación principal está en modo default, dontAsk, o plan, el subagente se ejecuta en el modo de permiso que establece, excepto bypassPermissions. Un subagente que declara bypassPermissions mantiene el modo de la conversación principal en su lugar. La excepción bypassPermissions requiere Claude Code v2.1.267 o posterior.

permissionMode acepta estos valores, y manual como alias para default:

Precargar skills en subagentes

Use el campo skills para inyectar contenido de skill en el contexto de un subagente al inicio. Esto da al subagente conocimiento de dominio sin requerir que descubra y cargue skills durante la ejecución.

---
name: api-developer
description: Implement API endpoints following team conventions
skills:
  - api-conventions
  - error-handling-patterns
---

Implement API endpoints. Follow the conventions and patterns from the preloaded skills.

El contenido completo de cada skill listada se inyecta en el contexto del subagente al inicio. Este campo controla qué skills se precargan, no qué skills el subagente puede acceder: sin él, el subagente aún puede descubrir e invocar skills de proyecto, usuario y plugin a través de la herramienta Skill durante la ejecución. Para evitar que un subagente invoque skills en absoluto, omita Skill de la lista tools o agréguelo a disallowedTools.

No puede precargar skills que establezcan disable-model-invocation: true, ya que la precarga se extrae del mismo conjunto de skills que Claude puede invocar. Esto incluye la skill integrada /verify: solo usted puede ejecutarla, por lo que tampoco puede ser precargada.

Si una skill listada falta o está deshabilitada, por ejemplo por la política de su organización, Claude Code la omite y registra una advertencia en el registro de depuración.

Habilitar memoria persistente

El campo memory da al subagente un directorio persistente que sobrevive entre conversaciones. El subagente usa este directorio para acumular conocimiento con el tiempo, como patrones de base de código, insights de depuración y decisiones arquitectónicas.

---
name: code-reviewer
description: Reviews code for quality and best practices
memory: user
---

You are a code reviewer. As you review code, update your agent memory with
patterns, conventions, and recurring issues you discover.

Elija un alcance basado en qué tan ampliamente debe aplicarse la memoria:

La memoria del subagente es parte de memoria automática: si desactiva la memoria automática, con la configuración autoMemoryEnabled o CLAUDE_CODE_DISABLE_AUTO_MEMORY, el campo memory no tiene efecto y el subagente se lanza sin las instrucciones de memoria o el acceso a la herramienta de memoria descrito a continuación.

Cuando la memoria está habilitada:

• El mensaje del sistema del subagente incluye instrucciones para leer y escribir en el directorio de memoria.
• El mensaje del sistema del subagente también incluye las primeras 200 líneas o 25KB de MEMORY.md en el directorio de memoria, lo que sea menor, con instrucciones para curar MEMORY.md si excede ese límite.
• Las herramientas Read, Write y Edit se habilitan automáticamente para que el subagente pueda administrar sus archivos de memoria.

Consejos de memoria persistente

• project es el alcance predeterminado recomendado. Hace que el conocimiento del subagente sea compartible a través de control de versiones.

• Pida al subagente que consulte su memoria antes de comenzar el trabajo: "Review this PR, and check your memory for patterns you've seen before."

• Pida al subagente que actualice su memoria después de completar una tarea: "Now that you're done, save what you learned to your memory." Con el tiempo, esto construye una base de conocimiento que hace que el subagente sea más efectivo.

• Incluya instrucciones de memoria directamente en el archivo markdown del subagente para que mantenga proactivamente su propia base de conocimiento:

  Update your agent memory as you discover codepaths, patterns, library
  locations, and key architectural decisions. This builds up institutional
  knowledge across conversations. Write concise notes about what you found
  and where.
  

Reglas condicionales con hooks

Para un control más dinámico sobre el uso de herramientas, use hooks PreToolUse para validar operaciones antes de que se ejecuten. Esto es útil cuando necesita permitir algunas operaciones de una herramienta mientras bloquea otras.

Este ejemplo crea un subagente que solo permite consultas de base de datos de solo lectura. El hook PreToolUse ejecuta el script especificado en command antes de que se ejecute cada comando Bash:

---
name: db-reader
description: Execute read-only database queries
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

Claude Code pasa la entrada del hook como JSON a través de stdin a comandos de hook. El script de validación lee este JSON, extrae el comando Bash y sale con código 2 para bloquear operaciones de escritura:

#!/bin/bash
# ./scripts/validate-readonly-query.sh

INPUT=$(cat)
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

# Block SQL write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)\b' > /dev/null; then
  echo "Blocked: Only SELECT queries are allowed" >&2
  exit 2
fi

exit 0

En macOS y Linux, haga el script ejecutable, o el hook falla en lugar de bloquear nada:

chmod +x ./scripts/validate-readonly-query.sh

Para probar la regla, pida al subagente que ejecute una declaración UPDATE: el script sale con código 2, Claude Code bloquea el comando, y el subagente ve el mensaje Blocked: Only SELECT queries are allowed.

Consulte Hook input para el esquema de entrada completo y códigos de salida para cómo los códigos de salida afectan el comportamiento. En Windows, escriba scripts de hook en PowerShell y agregue shell: powershell a la entrada del hook como se muestra en ejecutar hooks en PowerShell.

Deshabilitar subagentes específicos

Puede evitar que Claude use subagentes específicos agregándolos a la matriz deny en su configuración. Use el formato Agent(subagent-name) donde subagent-name coincida con el campo name del subagente.

{
  "permissions": {
    "deny": ["Agent(Explore)", "Agent(my-custom-agent)"]
  }
}

Esto funciona para subagentes integrados y personalizados. También puede usar la bandera CLI --disallowedTools:

claude --disallowedTools "Agent(Explore)"

Consulte la documentación de Permisos para más detalles sobre reglas de permisos.

Definir hooks para subagentes

Los subagentes pueden definir hooks que se ejecutan durante el ciclo de vida del subagente. Hay dos formas de configurar hooks:

• En el frontmatter del subagente: defina hooks que se ejecuten solo mientras ese subagente está activo
• En settings.json: defina hooks a nivel de sesión que también se disparen dentro de subagentes. Los eventos de herramientas como PreToolUse y PostToolUse se disparan para las llamadas de herramientas del subagente de la misma manera que en la conversación principal, y SubagentStart y SubagentStop se disparan cuando un subagente comienza o termina

Los hooks de archivos de configuración, configuración de política administrada y plugins todos se aplican dentro de subagentes, por lo que un hook PreToolUse en settings.json también se ejecuta antes de cada herramienta que usa un subagente.

Hooks en frontmatter de subagentes

Defina hooks directamente en el archivo markdown del subagente. Estos hooks solo se ejecutan mientras ese subagente específico está activo y se limpian cuando termina.

Para permitir que los hooks de frontmatter de un subagente a nivel de proyecto se ejecuten, acepte el diálogo de confianza del espacio de trabajo para la carpeta que contiene el archivo del agente. Los hooks de subagentes a nivel de usuario en ~/.claude/agents/ y de definiciones que pasa con --agents se ejecutan sin este paso. Si agregó una carpeta con --add-dir desde fuera del repositorio del espacio de trabajo de confianza, confíe en esa carpeta por separado: sus hooks .claude/agents/ no heredan la concesión del espacio de trabajo.

Hasta que confíe en la carpeta, el subagente aún se ejecuta, pero Claude Code omite sus hooks de frontmatter y registra un error en el registro de depuración explicando cómo confiar en la carpeta. Esta es una regla más estricta que la de los hooks en archivos de configuración: confiar en una carpeta principal no es suficiente, y una sesión -p no cuenta como de confianza. Lo que se ejecuta antes de confiar en una carpeta compara los dos. Antes de v2.1.218, los hooks de frontmatter podían ejecutarse desde carpetas que no había confiado, incluyendo en sesiones no interactivas.

Se soportan todos los eventos de hook. Los eventos más comunes para subagentes son:

Este ejemplo valida comandos Bash con el hook PreToolUse y ejecuta un linter después de ediciones de archivo con PostToolUse:

---
name: code-reviewer
description: Review code changes with automatic linting
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-command.sh $TOOL_INPUT"
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

Cuando el agente se invoca como un subagente, los hooks Stop en frontmatter se convierten automáticamente a eventos SubagentStop.

Hooks a nivel de proyecto para eventos de subagentes

Configure hooks en settings.json que respondan a eventos de ciclo de vida de subagentes en la sesión principal.

Ambos eventos soportan matchers para dirigirse a tipos de agentes específicos por nombre. El valor del matcher es el name del frontmatter del agente para subagentes a nivel de proyecto y usuario, o el identificador con alcance de plugin como my-plugin:db-agent para subagentes de plugin. Un nombre con alcance contiene dos puntos, por lo que se evalúa como una expresión regular sin anclar; anclarlo con ^ y $, como en ^my-plugin:db-agent$, para coincidir solo con ese agente.

Este ejemplo ejecuta un script de configuración solo cuando el subagente db-agent comienza, y un script de limpieza cuando cualquier subagente se detiene:

{
  "hooks": {
    "SubagentStart": [
      {
        "matcher": "db-agent",
        "hooks": [
          { "type": "command", "command": "./scripts/setup-db-connection.sh" }
        ]
      }
    ],
    "SubagentStop": [
      {
        "hooks": [
          { "type": "command", "command": "./scripts/cleanup-db-connection.sh" }
        ]
      }
    ]
  }
}

Un matcher con guiones como db-agent coincide exactamente en Claude Code v2.1.195 o posterior. En versiones anteriores se evalúa como una expresión regular sin anclar y también se dispara para cualquier tipo de agente que lo contenga, como prod-db-agent; anclarlo como ^db-agent$ en esas versiones.

Consulte Hooks para el formato de configuración de hook completo.

Trabajar con subagentes

Entender delegación automática

Claude delega automáticamente tareas basadas en la descripción de la tarea en su solicitud, el campo description en configuraciones de subagentes y el contexto actual. Para alentar delegación proactiva, incluya frases como "use proactively" en el campo description de su subagente.

Mantenga las descripciones breves: Claude Code muestra una advertencia de inicio cuando las descripciones combinadas de sus subagentes superan el límite de 15,000 tokens, y aún carga cada subagente.

Invocar subagentes explícitamente

Cuando la delegación automática no es suficiente, puede solicitar un subagente usted mismo. Tres patrones escalan desde una sugerencia única a un valor predeterminado de sesión completa:

• Lenguaje natural: nombre el subagente en su solicitud; Claude decide si delegar
• @-mention: garantiza que el subagente se ejecute para una tarea
• Sesión completa: toda la sesión usa el mensaje del sistema del subagente, restricciones de herramientas y modelo a través de la bandera --agent o la configuración agent

Para lenguaje natural, no hay sintaxis especial. Nombre el subagente y Claude típicamente delega:

Use the test-runner subagent to fix failing tests
Have the code-reviewer subagent look at my recent changes

@-mention el subagente. Escriba @ y elija el subagente del typeahead, de la misma manera que @-menciona archivos. Esto asegura que ese subagente específico se ejecute en lugar de dejar la opción a Claude:

@"code-reviewer (agent)" look at the auth changes

Su mensaje completo aún va a Claude, que escribe el mensaje de tarea del subagente basado en lo que pidió. El @-mention controla qué subagente Claude invoca, no qué mensaje recibe.

Los subagentes proporcionados por un plugin habilitado aparecen en el typeahead bajo su nombre con alcance, como my-plugin:code-reviewer o my-plugin:review:security cuando el plugin organiza agentes en subcarpetas. Los subagentes de fondo nombrados actualmente en ejecución en la sesión también aparecen en el typeahead, mostrando su estado junto al nombre.

También puede escribir la mención manualmente sin usar el selector: @agent-<name> para subagentes locales, o @agent- seguido del nombre con alcance para subagentes de plugin, por ejemplo @agent-my-plugin:code-reviewer. Mientras escribe esta forma, el typeahead muestra coincidencias de archivos en lugar de agentes. La mención del agente aún se resuelve cuando envía.

Ejecute toda la sesión como un subagente. Pase --agent <name> para iniciar una sesión donde el hilo principal en sí toma el mensaje del sistema del subagente, restricciones de herramientas y modelo:

claude --agent code-reviewer

El mensaje del sistema del subagente reemplaza completamente el mensaje del sistema predeterminado de Claude Code, de la misma manera que --system-prompt lo hace. Los archivos CLAUDE.md y la memoria del proyecto aún se cargan a través del flujo de mensajes normal. El nombre del agente aparece como @<name> en el encabezado de inicio para que pueda confirmar que está activo.

Esto funciona con subagentes integrados y personalizados, y la opción persiste cuando reanuda la sesión: Claude Code restaura el mensaje del sistema del agente, restricciones de herramientas y modelo junto con la conversación. Si el agente ya no existe cuando reanuda, la sesión continúa con las herramientas predeterminadas y muestra una advertencia que nombra el agente. Para el mensaje del sistema en cualquier caso, vea Banderas de mensaje del sistema en conversaciones reanudadas.

Para un subagente proporcionado por plugin, puede pasar solo el nombre del agente y Claude Code lo encontrará:

claude --agent security-reviewer

Si múltiples plugins proporcionan agentes con el mismo nombre, pase el nombre con alcance para desambiguar:

claude --agent my-plugin:security-reviewer

Si el plugin coloca el agente en una subcarpeta de su directorio agents/, incluya la subcarpeta en el nombre con alcance, por ejemplo claude --agent my-plugin:review:security.

Para hacerlo el predeterminado para cada sesión en un proyecto, establezca agent en .claude/settings.json:

{
  "agent": "code-reviewer"
}

La bandera CLI anula la configuración si ambas están presentes.

Ejecutar subagentes en primer plano o fondo

Los subagentes pueden ejecutarse en primer plano o en fondo:

• Subagentes en primer plano bloquean la conversación principal hasta completarse. Las solicitudes de permiso se le pasan a usted a medida que surgen.
• Subagentes en fondo se ejecutan concurrentemente mientras continúa trabajando. Cuando un subagente en fondo alcanza una llamada de herramienta que necesita permiso, Claude Code muestra la solicitud en su sesión principal y nombra el subagente que está preguntando. Apruebe para permitir que el subagente continúe, o presione Esc para denegar esa llamada de herramienta sin detener el subagente. Antes de v2.1.186, los subagentes en fondo denegaban automáticamente cualquier llamada de herramienta que habría solicitado.

Para cada subagente que Claude genera con la herramienta Agent, Claude Code elige primer plano o fondo del primero de estos casos que se aplica:

• Si un compañero de equipo de agentes en proceso generó el subagente, Claude Code lo ejecuta en primer plano. Claude Code rechaza con un error generar un subagente de compañero cuya definición establece background: true. Donde el modo fork está desactivado y usted no ha desactivado tareas en fondo, Claude Code también rechaza con un error cuando un compañero establece run_in_background: true.
• Si establece CLAUDE_CODE_DISABLE_BACKGROUND_TASKS en 1, Claude Code ejecuta el subagente en primer plano, en todo tipo de sesión y si el modo fork está activado o no.
• Donde el modo fork está activado, como lo está por defecto en una sesión interactiva, Claude Code ejecuta el subagente en fondo, subagentes fork y no-fork por igual, y Claude no puede pedir el primer plano.
• Donde el modo fork está desactivado, Claude ejecuta el subagente en fondo por defecto y en primer plano cuando necesita el resultado antes de continuar. El modo fork está desactivado en modo no interactivo con -p y en el SDK del Agent a menos que lo active. Para mantener un subagente particular en fondo incluso cuando Claude quiere el resultado, establezca su campo frontmatter background en true.

Para una habilidad con context: fork, Claude Code sigue las reglas en Ejecutar habilidades en un subagente en su lugar, si el modo fork está activado o no.

Los subagentes en fondo se ejecutan con un conjunto de herramientas integradas más pequeño que los subagentes en primer plano, excepto para forks de conversación y subagentes reanudados en primer plano.

Los subagentes en fondo muestran cada solicitud de permiso en su sesión principal. Cuando responde una de esas solicitudes con una opción que dura más allá de esa llamada de herramienta, como una concesión que dura el resto de la sesión, Claude Code aplica su respuesta a toda la sesión, incluyendo su conversación principal.

Un subagente en fondo puede dejar un comando Bash o PowerShell en fondo ejecutándose más allá del final de su turno. Cuando ese comando termina, Claude Code envía al subagente una notificación.

Los resultados de un subagente en fondo llegan a Claude como una notificación de finalización en un turno posterior. Claude espera esa notificación antes de reportar los resultados del subagente, y si pregunta sobre el progreso primero, reporta que el subagente aún se está ejecutando. Antes de v2.1.211, Claude a veces reportaba resultados para un subagente en fondo que no había terminado.

También puede dirigir esto usted mismo:

• Donde el modo fork está desactivado, pida a Claude que ejecute una tarea en fondo o en primer plano
• Presione Ctrl+B para poner en fondo una tarea en ejecución

Claude Code borra la fila de un subagente en fondo del panel de subagentes debajo de la entrada de solicitud de una de dos maneras, dependiendo de cómo terminó el subagente:

• Cuando un subagente termina exitosamente, Claude Code elimina su fila inmediatamente y, excepto en modo lector de pantalla, muestra /tasks to see subagents en el pie de página durante 30 segundos. Durante esos 30 segundos, ejecute /tasks y presione Enter en el subagente para abrir su transcripción. Antes de v2.1.232, Claude Code mantenía la fila durante 30 segundos después de que el subagente terminaba, igual que uno fallido, y no mostraba ninguna pista de pie de página.
• Cuando un subagente falla o usted lo detiene, Claude Code mantiene su fila durante 30 segundos. Para borrar la fila más rápido, selecciónela y presione x.

Un subagente en fondo que se completa permanece listado en /tasks, marcado como hecho y ordenado debajo del trabajo en ejecución, durante la misma ventana que la pista de pie de página anterior. Su vista de detalle permanece abierta cuando el subagente termina. Los subagentes que fallan o que usted detiene dejan la lista. Antes de v2.1.208, un subagente completado dejaba la lista en el momento en que terminaba y su vista de detalle se cerraba.

Nombres de subagentes

Claude puede dar a un subagente un nombre pasando un parámetro name en la llamada de herramienta Agent, y puede hacerlo por su cuenta, sin preguntarle primero. El nombre hace que el subagente sea direccionable: Claude puede enviarle un mensaje o reanudarlo por nombre después de que termine.

En una sesión interactiva con equipos de agentes habilitados, un subagente que Claude genera desde la conversación principal con un name se lanza como un compañero en su lugar, a menos que la llamada sea un fork o pase isolation en la llamada en sí. Un valor isolation en el frontmatter del subagente no lo previene, y el compañero entonces se ejecuta en el directorio de trabajo de la sesión principal. Vea Cómo Claude inicia equipos de agentes.

Errores de API en subagentes

Cuando algo corta la respuesta de un subagente a mitad de flujo, y la respuesta parcial contiene texto pero sin llamadas de herramientas, Claude Code solicita al subagente que continúe en lugar de terminar la ejecución. Esto sucede en sesiones interactivas también. La ejecución termina en el error solo una vez que esas continuaciones se agotan.

A partir de v2.1.199, un subagente cuya ejecución termina en un error de API, como un límite de uso o un error de servidor repetido, reporta esa falla de vuelta a Claude en lugar de devolver el texto de error como si fueran los hallazgos del subagente. Lo que Claude recibe depende de dónde se ejecutó el subagente:

• Primer plano: si un límite de velocidad, sobrecarga o error de servidor corta un subagente que ya produjo salida de texto, la herramienta Agent devuelve esa salida parcial con una nota de que el subagente fue cortado y no completó su tarea. Un subagente que no produjo nada, o cuya única salida fueron llamadas de herramientas, falla con Agent terminated early due to an API error, seguido del detalle del error. En v2.1.199, un límite de velocidad, sobrecarga o error de servidor que cortó la forma de solo llamadas de herramientas devolvió un resultado parcial vacío que contenía solo la nota de corte en su lugar.
• Fondo: el subagente se marca como fallido, y el mensaje que Claude recibe cuando termina nombra el error de API e incluye la última salida del subagente, por lo que el trabajo parcial no se pierde.

Cuando configura una cadena de modelos de respaldo y un subagente encuentra una falla que la cadena cubre, como su modelo no disponible, Claude Code cambia el subagente al primer modelo en la cadena que acepta la solicitud. El subagente continúa trabajando en lugar de terminar en el error.

Una vez que el error de API subyacente se resuelve, pida a Claude que reintente la tarea o reanude el subagente.

Escaneo de salida de subagentes

Claude Code escanea el informe final de cada subagente antes de que Claude lo lea. Un subagente puede haber leído archivos, páginas web o salida de comandos que nunca revisó, y el texto de esas fuentes puede llevar instrucciones dirigidas a la conversación principal. El escaneo nunca elimina ni reformula nada; hace dos tipos de cambios que puede notar en un informe:

• Inserción de barra invertida: el escaneo inserta una barra invertida en texto que imita la propia salida de Claude Code, como una etiqueta <system-reminder> o una línea que comienza con Human: o Assistant:, para que la imitación se lea como texto ordinario en lugar de ser confundida con parte de la conversación.
• Línea de marcador: el escaneo antepone una línea que comienza con [harness: subagent output matched instruction-shaped pattern(s): cuando el informe imita una etiqueta como <system-reminder> o menciona configuraciones de permiso como bypassPermissions o --dangerously-skip-permissions. Las menciones de configuración de permiso obtienen la línea de marcador, pero el texto en sí permanece como está escrito.

El escaneo no juzga si el contenido es malicioso, y no cambia lo que una instrucción en un informe puede hacer: una llamada de herramienta que el informe lleva a Claude a hacer aún pasa por los controles de permiso de la sesión y sandboxing. No es un sustituto para restringir lo que un subagente puede alcanzar.

Patrones comunes

Aislar operaciones de alto volumen

Uno de los usos más efectivos para subagentes es aislar operaciones que producen grandes cantidades de salida. Ejecutar pruebas, obtener documentación o procesar archivos de registro puede consumir contexto significativo. Al delegar estos a un subagente, la salida detallada permanece en el contexto del subagente mientras solo el resumen relevante regresa a su conversación principal.

Use a subagent to run the test suite and report only the failing tests with their error messages

Ejecutar investigación en paralelo

Para investigaciones independientes, genere múltiples subagentes para trabajar simultáneamente:

Research the authentication, database, and API modules in parallel using separate subagents

Cada subagente explora su área independientemente, luego Claude sintetiza los hallazgos. Esto funciona mejor cuando las rutas de investigación no dependen una de la otra.

Para trabajo que necesita mantener la ejecución en paralelo o no cabe en una ventana de contexto, ejecútelo en sesiones separadas y deje que Claude pase hallazgos entre ellas.

Encadenar subagentes

Para flujos de trabajo de múltiples pasos, pida a Claude que use subagentes en secuencia. Cada subagente completa su tarea y devuelve resultados a Claude, que luego pasa contexto relevante al siguiente subagente.

Use the code-reviewer subagent to find performance issues, then use the optimizer subagent to fix them

Elegir entre subagentes y conversación principal

Use la conversación principal cuando:

• La tarea necesita ida y vuelta frecuente o refinamiento iterativo
• Múltiples fases comparten contexto significativo, como planificación, implementación y prueba
• Está haciendo un cambio rápido y dirigido
• La latencia importa. Un subagente que no es un fork comienza de nuevo y puede necesitar tiempo para recopilar contexto

Use subagentes cuando:

• La tarea produce salida detallada que no necesita en su contexto principal
• Desea aplicar restricciones de herramientas específicas o permisos
• El trabajo es autónomo y puede devolver un resumen

Considere Skills en su lugar cuando desee mensajes reutilizables o flujos de trabajo que se ejecuten en el contexto de conversación principal en lugar de contexto de subagente aislado.

Para una pregunta sobre algo ya en su conversación, use /btw en lugar de un subagente. Ve su contexto completo pero no tiene acceso a herramientas, y la respuesta no se agrega al historial.

Permitir que subagentes generen sus propios subagentes

Por defecto, un subagente puede generar subagentes de su propio, hasta tres capas debajo de la conversación principal. En el límite de profundidad, Claude Code retiene la herramienta Agent de cada subagente excepto un fork, por lo que un subagente en el límite hace su trabajo delegado en sí mismo y devuelve un resumen. Un fork en el límite mantiene Agent en su lista de herramientas heredada, pero la herramienta devuelve un error en lugar de generar.

Los subagentes anidados se adaptan a una tarea delegada que en sí se divide en subtareas paralelas, como un subagente revisor que distribuye un verificador por hallazgo, por lo que la salida intermedia nunca llega a su conversación principal. Solo el resumen del subagente de nivel superior regresa a usted.

Para cambiar el límite, establezca CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH al número de capas de subagentes que desea debajo de su conversación principal. Por ejemplo, esta entrada en settings.json limita el anidamiento a dos capas:

{
  "env": {
    "CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH": "2"
  }
}

Con este valor, sus subagentes pueden delegar a una segunda capa de los suyos, y esa segunda capa no puede delegar más. Establezca 1 para desactivar el anidamiento.

Un subagente anidado se configura de la misma manera que uno de nivel superior y se resuelve desde los mismos alcances. Para evitar que un subagente genere mientras el anidamiento está activado, como un revisor que debe permanecer de solo lectura, omita Agent de su lista tools o añádalo a disallowedTools.

Claude Code muestra subagentes anidados como un árbol en el panel de subagentes debajo de la entrada de solicitud y marca cada fila que aún tiene descendientes en el panel con un recuento (+N) de ellos. Abra una fila para ver los hermanos de ese subagente e hijos directos con una ruta de regreso a main.

Límite de subagentes concurrentes

Dos límites controlan el uso de subagentes, cada uno con su propia variable: este detiene a Claude de generar más subagentes mientras demasiados se están ejecutando, y el límite de profundidad limita cuán profundamente se anidan los subagentes. No hay límite en el número total de subagentes que Claude puede generar durante una sesión.

Por defecto, cuando 20 subagentes se están ejecutando en una sesión, generar otro con la herramienta Agent falla con Concurrent subagent limit reached, y el error le dice a Claude que no reintente. La generación tiene éxito de nuevo cuando el recuento en ejecución cae por debajo del límite. Para cambiar el límite, establezca CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS a cualquier número entero positivo. Las sesiones con ultracode activo están exentas: el límite no se aplica allí. Requiere Claude Code v2.1.217 o posterior.

El límite bloquea solo subagentes que Claude genera con la herramienta Agent, pero otras ejecuciones ocupan los mismos espacios:

• Un fork en sesión que inicia con /subtask toma un espacio mientras se ejecuta y nunca es bloqueado por el límite.
• Reanudar un subagente que ya terminó toma un espacio nuevo sin verificar el límite, por lo que los reanudos pueden empujar el recuento en ejecución más allá de él.

Los agentes que otras características ejecutan, como agentes de workflow y compañeros de equipo de agentes, siguen sus propios límites en su lugar.

Administrar contexto de subagentes

Qué se carga al inicio

Cada subagente comienza con una ventana de contexto fresca e aislada. No ve su historial de conversación, las habilidades que ya ha invocado, o los archivos que Claude ya ha leído. Claude compone un mensaje de delegación que resume la tarea, y el subagente trabaja a partir de ahí. La excepción es un fork, que hereda la conversación principal en lugar de comenzar de nuevo.

El contexto inicial de un subagente que no es fork contiene:

• Mensaje del sistema: el mensaje del agente propio más detalles de entorno que Claude Code añade, no el mensaje del sistema de Claude Code. Los subagentes personalizados definen el suyo en el cuerpo markdown o campo prompt. Los agentes integrados tienen mensajes predefinidos.
• Mensaje de tarea: el mensaje de delegación que Claude escribe cuando entrega el trabajo.
• Archivos CLAUDE.md: cada nivel de la jerarquía de CLAUDE.md que la conversación principal carga, incluyendo ~/.claude/CLAUDE.md, reglas del proyecto, CLAUDE.local.md y archivos de política administrados. Los agentes integrados Explore y Plan omiten esto.
• Estado de Git: una instantánea tomada al inicio de la sesión principal. Ausente cuando el directorio de trabajo no es un repositorio de Git o cuando includeGitInstructions es false. Explore y Plan lo omiten de todas formas.
• Habilidades precargadas: contenido completo de cualquier habilidad nombrada en el campo skills del agente. Los agentes integrados no precargan habilidades.
• Roster de hermanos: un recordatorio del sistema que enumera main y cada otro agente nombrado en la sesión, cada uno un valor to válido para SendMessage. Requiere Claude Code v2.1.206 o posterior. El roster aparece solo cuando las herramientas del subagente incluyen SendMessage y al menos otro agente tiene un nombre, ya sea que Claude lo nombró cuando lo generó o se ejecuta como un compañero de equipo de agentes. Es una instantánea tomada cuando el subagente comienza, por lo que los agentes nombrados más tarde no aparecen.

Explore y Plan son los únicos subagentes que omiten CLAUDE.md y estado de Git. No hay campo de frontmatter o configuración por agente para cambiar qué agentes los omiten.

La conversación principal lee resultados de Explore y Plan con contexto completo de CLAUDE.md, por lo que la mayoría de reglas no necesitan llegar al subagente en sí. Si una regla debe, como "ignore el directorio vendor/", restate la en el mensaje que da a Claude cuando delega.

Algún estado de conversación principal nunca llega a un subagente que no es fork:

• Estilo de salida: un subagente ejecuta su propio mensaje del sistema, por lo que su estilo de salida no forma sus respuestas, excepto en un fork.
• Memoria automática: la memoria automática de la conversación principal no se carga. Para dar a un subagente memoria persistente de su propio, use el campo memory.
• Tamaño de ventana de contexto: la ventana de contexto de un subagente es dimensionada por su propio modelo, no la del principal. Delegar a un modelo con una ventana más pequeña da a ese subagente la ventana más pequeña.

Reanudar subagentes

Cada invocación de subagente crea una nueva instancia en lugar de continuar una anterior. Para continuar el trabajo de un subagente existente en lugar de comenzar de nuevo, pida a Claude que lo reanude.

Los subagentes reanudados retienen su historial de conversación completo, incluyendo todas las llamadas de herramientas anteriores, resultados y razonamiento. Si el subagente generó subagentes en fondo de su propio, ese historial incluye los resultados que entregaron mientras se ejecutaba. El subagente continúa exactamente donde se detuvo en lugar de comenzar de nuevo.

• Cuando un subagente se completa, Claude recibe su ID de agente.
• Los agentes integrados Explore y Plan son de una sola ejecución y no devuelven ID de agente, por lo que Claude no puede reanudarlo. Use general-purpose o un subagente personalizado cuando necesite continuar el trabajo.
• Cuando un subagente se detiene en su límite maxTurns, Claude Code marca la salida devuelta como parcial. Para subagentes que devuelven un ID de agente, Claude Code también nota en el resultado que Claude puede enviar un mensaje al subagente para continuar desde donde se detuvo.

Claude usa la herramienta SendMessage con el ID del agente o nombre como campo to para reanudarlo. SendMessage no requiere que equipos de agentes estén habilitados; solo los mensajes de protocolo de equipo estructurados como shutdown_request y plan_approval_response lo hacen. Más allá de subagentes y compañeros, en sesiones donde la mensajería entre sesiones está habilitada, Claude puede usar la misma herramienta para enviar mensajes a sus otras sesiones de Claude Code, en esta máquina o más allá de ella.

Para reanudar un subagente, pida a Claude que continúe el trabajo anterior:

Use the code-reviewer subagent to review the authentication module
[Agent completes]

Continue that code review and now analyze the authorization logic
[Claude resumes the subagent with full context from previous conversation]

Cuando Claude envía a un subagente completado un mensaje con la herramienta SendMessage, el subagente se reanuda automáticamente en el fondo sin una nueva invocación de Agent. Lo mismo aplica a un subagente que Claude detuvo con la herramienta TaskStop, una vez que su ejecución detenida ha salido. La ejecución reanudada mantiene el conjunto de herramientas de donde el subagente se ejecutó primero y puede mantener leyendo el caché de solicitud que la ejecución original calentó.

Un subagente que tiene la herramienta SendMessage puede enviar ese mensaje también. En una sesión interactiva, el agente reanudado entonces reporta de vuelta al subagente que lo reanudó, no a su conversación principal. Ese subagente espera el resultado antes de terminar su propio trabajo. Cuando un subagente envía un mensaje a un agente al que reporta, como su propio lanzador, Claude Code reanuda ese agente sin redirigir sus resultados.

Un subagente que usted detuvo, con x en /tasks o una solicitud SDK stop_task, no se reanuda automáticamente. Si Claude le envía un mensaje, el mensaje es rechazado y Claude es informado de que el agente fue cancelado.

Mientras la fila de ese subagente aún está en el panel de subagentes, escriba en su transcripción para reanudarlo usted mismo. Después de eso, un mensaje de Claude puede reanudarlo automáticamente de nuevo. Requiere Claude Code v2.1.191 o posterior.

Reanudar inicia una nueva ejecución del agente bajo el mismo ID, por lo que un subagente que ya había fallado o completado se muestra como ejecutándose de nuevo en la lista de tareas y en los eventos de tareas del SDK del Agent. Antes de v2.1.205, seguía mostrando su estado anterior fallido o completado mientras la ejecución reanudada estaba funcionando.

A partir de v2.1.199, SendMessage verifica que un nombre aún se refiera al mismo agente que alcanzó anteriormente en la conversación. Si un agente más nuevo ha tomado el nombre, como un subagente en fondo re-generado que lo reutilizó, Claude Code rechaza el envío en lugar de entregarlo al agente incorrecto, y el error reporta qué agente el nombre ahora alcanza para que Claude pueda redirigirse. Para alcanzar el agente anterior mientras aún se está ejecutando, Claude lo dirige por el ID del agente que recibió cuando generó ese agente. La verificación se limita a la conversación actual y se reinicia en /clear.

A partir de v2.1.198, un subagente trata los mensajes del agente que lo lanzó como dirección de tarea normal, incluyendo correcciones de curso a mitad de tarea, y actúa sobre ellos dentro de su propia configuración de permisos. Dos límites aún se mantienen independientemente de quién envió el mensaje: ningún mensaje de ningún agente cuenta como su aprobación para una solicitud de permiso pendiente, y ningún mensaje de agente puede cambiar la configuración de permisos de un subagente, CLAUDE.md o configuración. Solo el sistema de permisos o sus propios mensajes pueden otorgar aprobación.

También puede pedir a Claude el ID del agente si desea referenciarlo explícitamente, o encontrar IDs en los archivos de transcripción en ~/.claude/projects/{project}/{sessionId}/subagents/. Cada transcripción se almacena como agent-{agentId}.jsonl.

Las transcripciones de subagentes persisten independientemente de la conversación principal:

• Compactación de conversación principal: Cuando la conversación principal se compacta, las transcripciones de subagentes no se ven afectadas. Se almacenan en archivos separados.
• Persistencia de sesión: Las transcripciones de subagentes persisten dentro de su sesión. Puede reanudar un subagente después de reiniciar Claude Code reanudando la misma sesión.
• Limpieza automática: Claude Code elimina transcripciones de subagentes después del período de retención cleanupPeriodDays, 30 días por defecto, siguiendo las reglas de barrido de retención.

Auto-compactación

Los subagentes soportan compactación automática usando la misma lógica que la conversación principal. La compactación se dispara bajo las mismas condiciones, y CLAUDE_AUTOCOMPACT_PCT_OVERRIDE se aplica a subagentes también. Consulte variables de entorno para cuándo entra en vigor el override.

Los eventos de compactación se registran en archivos de transcripción de subagentes:

{
  "type": "system",
  "subtype": "compact_boundary",
  "compactMetadata": {
    "trigger": "auto",
    "preTokens": 167189
  }
}

El valor preTokens muestra cuántos tokens se usaron antes de que ocurriera la compactación.

Bifurcar la conversación actual

Un fork es un subagente que hereda toda la conversación hasta ahora en lugar de comenzar de nuevo. Esto elimina el aislamiento de entrada que los subagentes de otra manera proporcionan: un fork ve el mismo mensaje del sistema, herramientas, modelo e historial de mensajes que la sesión principal, para que pueda entregarle una tarea secundaria sin re-explicar la situación. Las propias llamadas de herramientas del fork aún permanecen fuera de su conversación y solo su resultado final regresa, por lo que su ventana de contexto principal permanece limpia. Use un fork cuando cualquier otro subagente necesitaría demasiado contexto para ser útil, o cuando desee probar varios enfoques en paralelo desde el mismo punto de partida.

Claude inicia un fork solicitando el tipo de subagente fork a través de la herramienta Agent. Usted controla si puede hacerlo con modo fork, que está activado de forma predeterminada en sesiones interactivas.

Puede iniciar un fork usted mismo con /subtask seguido de una tarea, independientemente de si el modo fork está activado o no. En v2.1.161 a v2.1.211, el comando es /fork. Claude Code nombra el fork a partir de las primeras palabras de la tarea. El siguiente ejemplo bifurca la conversación para redactar casos de prueba mientras continúa con la implementación en la sesión principal:

/subtask draft unit tests for the parser changes so far

El fork aparece en un panel debajo de su solicitud y se ejecuta en el fondo mientras continúa trabajando. Cuando termina, su resultado llega como un mensaje en su conversación principal. La siguiente sección cubre los controles del panel para observar y dirigir forks mientras se ejecutan.

Observar y dirigir forks en ejecución

Los forks en ejecución aparecen en un panel debajo de la entrada de solicitud, con una fila para la sesión principal y una para cada fork.

Cuando un fork termina exitosamente, Claude Code elimina su fila. Claude Code mantiene la fila de un fork que falló o que usted detuvo durante 30 segundos, lo mismo que para cualquier otro subagente de fondo. Antes de v2.1.232, Claude Code también mantenía la fila de un fork terminado durante 30 segundos.

Use estas teclas para interactuar con el panel:

Con la transcripción de un fork o subagente abierta, los mensajes de seguimiento y las skills van a ese agente, pero los comandos integrados aún se ejecutan en su conversación principal. A partir de v2.1.199, escribir /model o /fast en esa vista muestra un aviso de que cambia el modelo de la conversación principal o el modo rápido, no el del agente visto, en lugar de ejecutarlo silenciosamente.

Cómo los forks difieren de otros subagentes

Un fork hereda todo lo que la sesión principal tiene en el momento en que se genera. Cualquier otro subagente comienza desde cero a partir de su definición.

Porque el mensaje del sistema del fork y las definiciones de herramientas son idénticas al principal, su primera solicitud reutiliza la caché de solicitud del principal. Esto hace que bifurcar sea más económico que generar un subagente fresco para tareas que necesitan el mismo contexto.

Cuando Claude genera un fork a través de la herramienta Agent, puede pasar isolation: "worktree" para que las ediciones de archivo del fork se escriban en un git worktree separado en lugar de su checkout. Un fork no puede generar más forks.

Activar o desactivar el modo fork

Claude Code activa el modo fork de forma predeterminada en sesiones interactivas y lo deja desactivado de forma predeterminada en modo no interactivo con -p y en el Agent SDK. El valor predeterminado interactivo requiere Claude Code v2.1.232 o posterior. En versiones anteriores, establezca CLAUDE_CODE_FORK_SUBAGENT en 1 para activar el modo fork.

Puede saber que el modo fork está activado por cómo Claude Code maneja la herramienta Agent:

• Claude puede generar un fork solicitando el tipo de subagente fork. Cuando Claude no solicita un tipo, obtiene el subagente general-purpose, si la sesión aún tiene ese tipo. Los subagentes generados a partir de una definición, como Explore, funcionan como de costumbre.
• Claude Code ejecuta los subagentes que Claude genera en el fondo, forks y subagentes que no son fork por igual, aparte de los casos que permanecen en primer plano. Claude Code también elimina el parámetro run_in_background de la herramienta Agent, por lo que Claude no puede solicitar el primer plano.

Establezca la variable de entorno CLAUDE_CODE_FORK_SUBAGENT para anular los valores predeterminados:

• 1 activa el modo fork en modo no interactivo y el Agent SDK también
• 0 desactiva el modo fork en todo tipo de sesión

Para mantener el modo fork activado pero evitar que Claude genere forks, deniegue el tipo de subagente fork con una regla Agent(fork). Claude Code aún ejecuta los subagentes que Claude genera en el fondo, aparte de los mismos casos que permanecen en primer plano.

Subagentes de ejemplo

Estos ejemplos demuestran patrones efectivos para construir subagentes. Úselos como puntos de partida, o genere una versión personalizada con Claude.

Revisor de código

Un subagente de solo lectura que revisa código sin modificarlo. Este ejemplo muestra cómo diseñar un subagente enfocado con acceso limitado a herramientas que excluye Edit y Write, y un mensaje detallado que especifica exactamente qué buscar y cómo formatear la salida.

---
name: code-reviewer
description: Expert code review specialist. Proactively reviews code for quality, security, and maintainability. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---

You are a senior code reviewer ensuring high standards of code quality and security.

When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Begin review immediately

Review checklist:
- Code is clear and readable
- Functions and variables are well-named
- No duplicated code
- Proper error handling
- No exposed secrets or API keys
- Input validation implemented
- Good test coverage
- Performance considerations addressed

Provide feedback organized by priority:
- Critical issues (must fix)
- Warnings (should fix)
- Suggestions (consider improving)

Include specific examples of how to fix issues.

Depurador

Un subagente que puede analizar y corregir problemas. A diferencia del revisor de código, este incluye Edit porque corregir errores requiere modificar código. El mensaje proporciona un flujo de trabajo claro desde diagnóstico hasta verificación.

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
---

You are an expert debugger specializing in root cause analysis.

When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate the failure location
4. Implement minimal fix
5. Verify solution works

Debugging process:
- Analyze error messages and logs
- Check recent code changes
- Form and test hypotheses
- Add strategic debug logging
- Inspect variable states

For each issue, provide:
- Root cause explanation
- Evidence supporting the diagnosis
- Specific code fix
- Testing approach
- Prevention recommendations

Focus on fixing the underlying issue, not the symptoms.

Científico de datos

Un subagente específico de dominio para trabajo de análisis de datos. Este ejemplo muestra cómo crear subagentes para flujos de trabajo especializados fuera de tareas de codificación típicas. Establece explícitamente model: sonnet para análisis más capaz.

---
name: data-scientist
description: Data analysis expert for SQL queries, BigQuery operations, and data insights. Use proactively for data analysis tasks and queries.
tools: Bash, Read, Write
model: sonnet
---

You are a data scientist specializing in SQL and BigQuery analysis.

When invoked:
1. Understand the data analysis requirement
2. Write efficient SQL queries
3. Use BigQuery command line tools (bq) when appropriate
4. Analyze and summarize results
5. Present findings clearly

Key practices:
- Write optimized SQL queries with proper filters
- Use appropriate aggregations and joins
- Include comments explaining complex logic
- Format results for readability
- Provide data-driven recommendations

For each analysis:
- Explain the query approach
- Document any assumptions
- Highlight key findings
- Suggest next steps based on data

Always ensure queries are efficient and cost-effective.

Validador de consultas de base de datos

Un subagente que permite acceso a Bash pero valida comandos para permitir solo consultas SQL de solo lectura. Este ejemplo muestra cómo usar hooks PreToolUse para validación condicional cuando necesita control más fino que el campo tools proporciona.

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---

You are a database analyst with read-only access. Execute SELECT queries to answer questions about the data.

When asked to analyze data:
1. Identify which tables contain the relevant data
2. Write efficient SELECT queries with appropriate filters
3. Present results clearly with context

You cannot modify data. If asked to INSERT, UPDATE, DELETE, or modify schema, explain that you only have read access.

Claude Code pasa la entrada del hook como JSON a través de stdin a comandos de hook. El script de validación lee este JSON, extrae el comando siendo ejecutado, y lo verifica contra una lista de operaciones de escritura SQL. Si se detecta una operación de escritura, el script sale con código 2 para bloquear la ejecución y devuelve un mensaje de error a Claude a través de stderr.

Cree el script de validación en cualquier lugar en su proyecto. La ruta debe coincidir con el campo command en su configuración de hook:

#!/bin/bash
# Blocks SQL write operations, allows SELECT queries

# Read JSON input from stdin
INPUT=$(cat)

# Extract the command field from tool_input using jq
COMMAND=$(echo "$INPUT" | jq -r '.tool_input.command // empty')

if [ -z "$COMMAND" ]; then
  exit 0
fi

# Block write operations (case-insensitive)
if echo "$COMMAND" | grep -iE '\b(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE|REPLACE|MERGE)\b' > /dev/null; then
  echo "Blocked: Write operations not allowed. Use SELECT queries only." >&2
  exit 2
fi

exit 0

En macOS y Linux, haga el script ejecutable:

chmod +x ./scripts/validate-readonly-query.sh

En Windows, escriba el script de validación en PowerShell y agregue shell: powershell a la entrada del hook. Consulte ejecutar hooks en PowerShell.

El hook recibe JSON a través de stdin con el comando Bash en tool_input.command. El código de salida 2 bloquea la operación y alimenta el mensaje de error de vuelta a Claude. Consulte Hooks para detalles sobre códigos de salida e Hook input para el esquema de entrada completo.

El mensaje del sistema le dice al subagente que rechace solicitudes de escritura, por lo que el hook es una red de seguridad: si el subagente intenta una escritura de todas formas, Claude Code bloquea el comando y el subagente ve el mensaje Blocked: Write operations not allowed. Use SELECT queries only..

Próximos pasos

Ahora que entiende subagentes, explore estas características relacionadas:

• Distribuir subagentes con plugins para compartir subagentes entre equipos o proyectos
• Ejecutar Claude Code programáticamente con el Agent SDK para CI/CD y automatización
• Usar servidores MCP para dar a los subagentes acceso a herramientas y datos externos