Crear subagentes personalizados

• 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

Subagentes integrados

• Para bloquear un tipo integrado específico, agréguelo a permissions.deny como se muestra en Disable specific subagents.
• Para evitar que Claude delegue en ningún subagente, niegue la herramienta Agent misma 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 delegar en ellos. 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.

Inicio rápido: crea tu primer subagente

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

Configurar subagentes

Elegir el alcance del subagente

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."
  }
}
'@

• prompt: el mensaje del sistema del agente, equivalente al cuerpo markdown en subagentes basados en archivos. prompt puede estar vacío. Si selecciona un agente con un prompt vacío y sin campo memory como el agente de la sesión con --agent, el mensaje del sistema de la sesión se deja sin cambios. Un prompt vacío requiere Claude Code v2.1.281 o posterior.
• Campos de frontmatter: description, tools, disallowedTools, model, permissionMode, mcpServers, hooks, maxTurns, autoCompactWindow, skills, initialPrompt, memory, effort, background, omitClaudeMd, e isolation.
• Campos ignorados: color y experimental no se aceptan aquí y se ignoran en lugar de rechazarse.

Escribir archivos de subagentes

---
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.

• 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.

Referencia de frontmatter

• Para encontrar un campo mal escrito en un subagente que se cargó, ejecuta claude --debug en tu shell y busca does not recognize or apply en el registro de depuración en ~/.claude/debug/<session-id>.txt. El registro de depuración nombra hasta cinco campos de nivel superior del archivo del subagente que Claude Code no reconoce, junto con el nombre que probablemente querías usar cuando un campo admitido es similar. Requiere Claude Code v2.1.296 o posterior.
• Para averiguar por qué un archivo de subagente no se cargó, consulta Archivos de subagente que Claude Code omite.

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

Archivos de subagente que Claude Code omite

• 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 -, contiene : o tiene más de 256 caracteres: Claude Code omite el archivo y escribe un error en el registro de depuración.
• 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.

Verificar un directorio agents antes de una sesión

Elegir un modelo

• 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-5 o claude-sonnet-5. Acepta los mismos valores que la bandera --model
• inherit: use el mismo modelo que la conversación principal

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

• El modelo de la conversación principal pertenece a esa familia: el subagente se ejecuta en el modelo exacto de la conversación principal, incluyendo cualquier sufijo [1m], por lo que obtiene la misma ventana de contexto extendido que la conversación principal.
• Claude Code no puede determinar la familia del modelo de la conversación principal, en un proveedor distinto de la API de Anthropic: esto puede suceder con un ARN de perfil de inferencia de aplicación en Amazon Bedrock que Claude Code no ha resuelto a un modelo de respaldo. Este caso cubre solo el alias opus, y no se aplica cuando establece ANTHROPIC_DEFAULT_OPUS_MODEL, ya que opus entonces se resuelve al modelo que establece.

• 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.

Ejecutar cada subagente en un modelo

• Si establece ambas variables, los subagentes se ejecutan en el modelo en CLAUDE_CODE_SUBAGENT_MODEL.
• Si estableces solo CLAUDE_CODE_SUBAGENT_MODEL_FORCE, los subagentes se ejecutan en el modelo de la conversación principal, excepto el subagente integrado Explore, que se ejecuta en el modelo indicado para él en Subagentes integrados.

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

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

Elegir un nivel de esfuerzo

Cuando un subagente no tiene campo ni parámetro effort

Controlar capacidades de subagentes

Herramientas disponibles

• 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
• WaitForMcpServers
• Workflow

Restringir qué herramientas puede usar un subagente

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

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

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

Nombres de servidores MCP que contienen un doble guion bajo

• En tools: escribe mcp__ seguido del nombre completo del servidor y __*, como en mcp__reports__v2__*. Sin el __* final, mcp__reports__v2 no coincide con ninguna de las herramientas de ese servidor.
• En disallowedTools: busca mcp__reports o mcp__reports__*, las entradas que retienen un servidor llamado reports. Con cualquiera de las dos entradas, el subagente también pierde todas las herramientas de reports__v2, porque esos nombres de herramientas también comienzan con mcp__reports__. Para retener solo las herramientas del servidor reports, enuméralas una por una, como mcp__reports__run_query.

Restringir qué subagentes pueden ser generados

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

tools: Agent, Read, Bash

Alcance de servidores MCP a un subagente

---
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.

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

Confianza requerida para servidores MCP en línea

• 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

• 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

Modos de permiso

• 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 el subagente termina, el clasificador también revisa su trabajo y su informe final antes de que el informe se entregue, como Cómo el modo auto maneja subagentes describe. Si un subagente pide permiso mientras la conversación principal está en bypassPermissions, comprueba si su llamada a herramienta es una de las acciones que ningún modo aprueba automáticamente.
• Cuando la conversación principal está en modo plan, el subagente permanece en modo plan sea cual sea el permissionMode que establezcas, a menos que se ejecute como compañero de un equipo de agentes bajo las reglas de equipos de agentes. Si estableces dontAsk, el subagente tampoco te pide nada: una acción que el modo plan te pediría aprobar se deniega en su lugar.
• Cuando la conversación principal está en modo default o dontAsk, el subagente se ejecuta en el modo de permisos que estableces. En su lugar, mantiene el modo de permisos de la conversación principal en estos casos:
  • Estableces bypassPermissions. La excepción de bypassPermissions requiere Claude Code v2.1.267 o posterior.
  • Estableces auto y el modo automático no está disponible para el subagente, por ejemplo cuando un archivo de configuración establece disableAutoMode o el modelo del subagente no soporta el modo automático.

Precargar skills en subagentes

---
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.

Habilitar memoria persistente

---
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.

• 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

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

#!/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

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

Deshabilitar subagentes específicos

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

claude --disallowedTools "Agent(Explore)"

Definir hooks para subagentes

• 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

Hooks en frontmatter de subagentes

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

Hooks a nivel de proyecto para eventos de subagentes

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

Trabajar con subagentes

Entender la delegación automática

Invocar subagentes explícitamente

• Lenguaje natural: nombra el subagente en tu prompt; Claude decide si delega
• @-mention: garantiza que el subagente se ejecute para una tarea
• Sesión completa: toda la sesión se ejecuta como ese subagente a través del flag --agent o el ajuste agent

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

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

claude --agent code-reviewer

claude --agent security-reviewer

claude --agent my-plugin:security-reviewer

{
  "agent": "code-reviewer"
}

Ejecutar subagentes en primer plano o en segundo plano

• Subagentes en primer plano bloquean la conversación principal hasta completarse. Las solicitudes de permiso se te pasan a medida que surgen.
• Subagentes en segundo plano se ejecutan concurrentemente mientras continúas trabajando. Cuando un subagente en segundo plano llega a una llamada a herramienta que necesita permiso, Claude Code muestra la solicitud en tu sesión principal y nombra el subagente que está pidiendo. Aprueba para permitir que el subagente continúe, o presiona Esc para negar esa llamada a herramienta sin detener el subagente.

Qué subagentes se ejecutan en segundo plano

• claude -p y el Agent SDK: Claude puede esperar, por su propio criterio o cuando se lo pides.
• Sesiones interactivas en la terminal, VS Code y la aplicación de escritorio en tu máquina: para permitir que Claude espere a un subagente, desactiva el modo fork, que está activado por defecto.

Permitir que Claude espere a un subagente

1. Desactiva el modo fork estableciendo CLAUDE_CODE_FORK_SUBAGENT en 0, por ejemplo en settings.json:
   {
     "env": {
       "CLAUDE_CODE_FORK_SUBAGENT": "0"
     }
   }
   
2. Ejecuta claude de nuevo desde tu shell, o abre una nueva conversación de VS Code.
3. Pide a Claude que espere cuando necesites un resultado primero, por ejemplo “run the reviewer subagent and wait for its report”.

Herramientas, permisos y resultados de los subagentes en segundo plano

Subagentes terminados en el panel y la lista de tareas

• 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, ejecuta /tasks y presiona 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 terminara, igual que uno fallido, y no mostraba ninguna pista de pie de página.
• Cuando un subagente falla o lo detienes, Claude Code mantiene su fila durante 30 segundos. Para borrar la fila más rápido, selecciónala y presiona x.

Nombres de subagentes

Errores de API en subagentes

• Primer plano: si un rate limit, 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 a herramientas, falla con Agent terminated early due to an API error, seguido del detalle del error.
• Segundo plano: 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.

⚠ This agent switched to <model> because its earlier model could not be used.

Escaneo de salida de subagentes

• Inserción de barra invertida: el escaneo inserta una barra invertida en texto que imita la salida propia 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 ajustes de permisos como bypassPermissions o --dangerously-skip-permissions. Las menciones de ajustes de permisos obtienen la línea de marcador, pero el texto en sí permanece como está escrito.

Patrones comunes

Aislar operaciones de alto volumen

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

Ejecutar investigación en paralelo

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

Encadenar subagentes

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

Elegir entre subagentes y conversación principal

• La tarea necesita ida y vuelta frecuente o refinamiento iterativo
• Múltiples fases comparten contexto significativo, como planificación, implementación y pruebas
• Estás 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 reunir contexto

• La tarea produce salida detallada que no necesitas en tu contexto principal
• Quieres aplicar restricciones de herramientas o permisos específicos
• El trabajo es autónomo y puede devolver un resumen

Dejar que los subagentes generen sus propios subagentes

• Sesión interactiva en la terminal: solo el resumen del subagente de nivel superior regresa a ti, porque un subagente que lanza subagentes en segundo plano espera sus resultados antes de terminar.
• claude -p y el Agent SDK: el subagente que los genera espera mientras el modo fork está activado. Si desactivas el modo fork, los subagentes anidados comienzan en segundo plano en su lugar. El subagente que los genera no espera a un subagente anidado en segundo plano, que reporta a tu conversación principal si dura más que el subagente que lo generó.

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

Límite de subagentes concurrentes

• Un fork en sesión que inicias 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 las reanudaciones pueden empujar el conteo en ejecución más allá de él.

Gestionar contexto de subagentes

Qué se carga al inicio

• Prompt del sistema: el prompt propio del agente más detalles del entorno que Claude Code añade, no el prompt del sistema de Claude Code. Los subagentes personalizados definen el suyo en el cuerpo markdown o el campo prompt. Los agentes integrados tienen prompts predefinidos.
• Mensaje de tarea: el prompt de delegación que Claude escribe cuando entrega el trabajo.
• Archivos CLAUDE.md: cada nivel de la jerarquía CLAUDE.md que la conversación principal carga, incluyendo ~/.claude/CLAUDE.md, reglas del proyecto, CLAUDE.local.md, archivos de política administrada, y cualquier archivo AGENTS.md cargado como instrucciones del proyecto. Los agentes integrados Explore y Plan omiten esto. Un subagente cuya definición establece omitClaudeMd carga solo los archivos de política administrada, o ninguno en absoluto cuando la definición viene de la configuración administrada.
• Estado de Git: una instantánea que Claude Code lee de tu repositorio cuando el subagente comienza. Para un subagente en su propio worktree de ese repositorio, la instantánea muestra la rama, el estado y los commits recientes del worktree. Ausente fuera de un repositorio Git o siempre que la instantánea esté desactivada; consulta includeGitInstructions. Explore y Plan la omiten independientemente.
• Skills precargados: contenido completo de cualquier skill nombrado en el campo skills del agente. Los agentes integrados no precargan skills.
• Roster de hermanos: un recordatorio del sistema listando main y cada otro agente nombrado en la sesión, cada uno un valor to válido para SendMessage. 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ó al generarlo o se ejecuta como compañero de equipo de agentes. Es una instantánea tomada cuando el subagente comienza, por lo que los agentes nombrados después no aparecen.

• Estilo de salida: un subagente ejecuta su propio prompt del sistema, por lo que tu 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 propia, usa el campo memory.
• Tamaño de ventana de contexto: la ventana de contexto de un subagente se dimensiona por su propio modelo, no por el del padre. Delegar a un modelo con una ventana más pequeña da a ese subagente la ventana más pequeña.

Reanudar subagentes

• Cuando un subagente se completa, Claude recibe su ID de agente.
• Los agentes integrados Explore y Plan son de una sola vez y no devuelven un ID de agente, por lo que Claude no puede reanudarlos. Usa general-purpose o un subagente personalizado cuando necesites continuar el trabajo.
• Cuando un subagente se detiene en su límite maxTurns, Claude Code marca la salida devuelta como parcial, y Claude puede reanudar el subagente para continuar su trabajo.

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]

• 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. Puedes reanudar un subagente después de reiniciar Claude Code reanudando la misma sesión.
• Limpieza automática: Claude Code elimina las 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.

Enviar un mensaje a un subagente por nombre después de un reinicio

Compactación automática

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

Establecer la ventana de compactación automática para un subagente

---
name: log-reader
description: Reads long log files and reports the errors it finds
autoCompactWindow: 200000
---

• El valor no es inferior a la ventana de compactación automática que el subagente heredaría de otro modo: para compactar antes, establece un valor inferior a esa ventana.
• Ejecutas toda la sesión como este subagente con --agent o el ajuste agent: el campo no tiene efecto allí. Para establecer la ventana de la sesión, consulta Establecer la ventana de compactación automática.

Bifurcar la conversación actual

/subtask draft unit tests for the parser changes so far

Observar y dirigir forks en ejecución

• /compact, /clear y /rewind actúan sobre la conversación principal, por lo que Claude Code te pide que confirmes antes de ejecutar uno de ellos desde esta vista.
• /model y /fast establecen el modelo y el modo rápido de la conversación principal, no los del agente visto, por lo que no se ejecutan desde esta vista. Un aviso te indica el motivo.

Cómo los forks difieren de otros subagentes

Desactivar el modo fork

• Detener solo los forks: agrega "Agent(fork)" a permissions.deny en tu configuración.
• Desactivar el modo fork: establece CLAUDE_CODE_FORK_SUBAGENT en 0, siguiendo los pasos de Permitir que Claude espere a un subagente.

Subagentes de ejemplo

Revisor de código

---
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

---
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

---
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

---
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.

#!/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

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

Próximos pasos

• 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