03
Nivel 03 · Avanzado

Extender el agente

Convierte a Claude Code en una herramienta hecha a medida: reglas que se cumplen siempre, especialistas a los que delegar, procedimientos reutilizables, conexión con tus sistemas y aislamiento real.

Lección 3.1

Hooks: el ciclo de vida

Un hook ejecuta tu script, un request HTTP, una herramienta MCP, un prompt o un subagente cuando Claude Code llega a un evento del ciclo de vida. La diferencia clave: una instrucción en CLAUDE.md es un pedido; un hook es una garantía. Siempre se dispara en su evento y no cuesta contexto salvo que devuelva texto.

Simulador de ciclo de vida

Eventos más usados

EventoCuándo se dispara¿Bloquea?
SessionStartAl iniciar o retomar (matchers: startup, resume, clear, compact)No; su stdout se agrega al contexto
UserPromptSubmitAntes de procesar tu promptSí
PreToolUseAntes de una herramientaSí
PermissionRequestCuando Claude Code va a pedirte permisoPuede aprobar o denegar
PostToolUseDespués de que la herramienta tuvo éxitoNo puede deshacer; sí puede dar feedback
Stop / SubagentStopCuando Claude o un subagente termina de responderSí: obliga a seguir trabajando
NotificationCuando Claude espera input o permisoNo
PreCompact / PostCompactAlrededor de la compactación—
ConfigChangeCuando cambia un archivo de configuración durante la sesiónSí
SessionEndAl terminar la sesiónNo

Hay más de 30 eventos en total, incluidos PostToolUseFailure, SubagentStart, TaskCreated, TaskCompleted, InstructionsLoaded, CwdChanged, FileChanged, WorktreeCreate y Elicitation.

Lección 3.2

Hooks: códigos de salida y JSON

Un hook de tipo command recibe el evento como JSON por stdin y responde con su código de salida, stdout y stderr. Prueba combinaciones:

Probador de salida de hooks
El error más comúnexit 1 no bloquea: es un error no bloqueante y la acción sigue. Para imponer una política, usa exit 2 (con el motivo en stderr) o exit 0 con JSON. Elige un enfoque por hook.

Salida JSON estructurada

stdout de un hook PreToolUse
{
  "hookSpecificOutput": {
    "hookEventName": "PreToolUse",
    "permissionDecision": "deny",
    "permissionDecisionReason": "Usa rg en vez de grep"
  }
}
  • permissionDecision: "allow" salta el prompt (las reglas deny y ask siguen aplicando), "deny" cancela y le da el motivo a Claude, "ask" muestra el prompt normal.
  • Si varios hooks responden, gana la decisión más restrictiva: deny > defer > ask > allow. Todos los hooks corren en paralelo hasta terminar.
  • PostToolUse y Stop usan "decision": "block" en el nivel superior; PermissionRequest usa hookSpecificOutput.decision.behavior.
  • Para inyectar contexto desde UserPromptSubmit, usa hookSpecificOutput.additionalContext. Si lo pones en el nivel superior, se ignora sin aviso.
  • Un PreToolUse puede reescribir los argumentos de la herramienta con updatedInput.

Tipos de hook y timeouts

TipoQué haceTimeout default
commandCorre un comando de shell10 min (30 s en UserPromptSubmit)
httpPOST del JSON a una URL; útil para auditoría centralizada10 min
mcp_toolLlama una herramienta de un servidor MCP10 min
promptUn modelo decide con {"ok": true/false, "reason": "…"}30 s
agent experimentalUn subagente verifica con herramientas (hasta 50 turnos)60 s
Lección 3.3

Construye un hook: recetas

Los hooks viven en settings con tres niveles: evento → grupo con matcher → handlers. El matcher filtra por nombre de herramienta (Edit|Write, Bash, mcp__github__.* como regex); if filtra por argumentos con sintaxis de permisos.

Constructor de hooks

Script de bloqueo de ejemplo (.claude/hooks/block-rm.sh):

bash
#!/bin/bash
command=$(jq -r '.tool_input.command' <<<"$(cat)")
if [[ "$command" == rm* ]]; then
  echo "Bloqueado: no se permite rm" >&2   # stderr = feedback para Claude
  exit 2                                    # 2 = bloquear
fi
exit 0                                      # 0 = sin objeción
  • Dónde van: ~/.claude/settings.json, .claude/settings.json, .claude/settings.local.json, managed settings, plugins (hooks/hooks.json) o el frontmatter de skills y subagentes. Todos se suman: si un hook está en dos lugares, corre dos veces.
  • Usa ${CLAUDE_PROJECT_DIR} en las rutas para que funcionen desde cualquier subdirectorio.
  • /hooks muestra lo configurado. Para depurar, mira el log de debug: qué hooks calzaron, su código de salida y su salida.
  • Claude puede escribirlos por ti: "escribe un hook que corra eslint después de cada edición".
A fondoHooks a fondoLos 30+ eventos, simulador de salida, recetario y constructor.→
Lección 3.4

Subagentes: cómo funcionan

Un subagente es un trabajador con su propia ventana de contexto, su propio system prompt y su propio set de herramientas. Puede leer decenas de archivos; a tu conversación solo vuelve un resumen. Como el contexto es tu recurso más escaso, esto es lo que los hace valiosos.

Qué carga al iniciar (no-fork)

  • Su propio system prompt (no el de Claude Code) más detalles del entorno.
  • El mensaje de tarea que Claude le escribe. No ve tu historial ni los archivos ya leídos.
  • Toda la jerarquía de CLAUDE.md y un snapshot de git (Explore y Plan omiten ambos).
  • El contenido completo de las skills listadas en su campo skills.
  • No hereda estilos de salida ni tu auto memory.

Un fork es distinto: copia tu conversación completa. Lánzalo con /subtask <tarea> (corre en segundo plano y devuelve el resultado). /fork copia toda la sesión a una sesión en segundo plano nueva.

Subagentes incluidos

NombrePropósito
ExploreBúsqueda y análisis rápido de solo lectura
PlanInvestigación de solo lectura en plan mode
general-purposeTareas de varios pasos que exploran y modifican
claude-code-guideResponde preguntas sobre Claude Code
statusline-setupConfigura la status line

Primer plano y segundo plano

Sin configurar nada, los subagentes que Claude lanza desde la conversación principal corren en segundo plano: sigues trabajando y sus prompts de permiso aparecen en tu sesión indicando qué subagente pregunta. Los de primer plano bloquean la conversación. /tasks lista y administra todo lo que corre en segundo plano; Ctrl+B manda tareas en curso al fondo.

prompts
Usa subagentes para investigar cómo nuestro sistema de auth maneja el refresh de tokens
Investiga los módulos de auth, base de datos y API en paralelo con subagentes separados
Usa un subagente para correr la suite de tests y reportar solo los que fallan con su error
Usa el subagente code-reviewer para encontrar problemas de rendimiento y luego el optimizer para arreglarlos
  • Límites: 20 subagentes concurrentes (CLAUDE_CODE_MAX_CONCURRENT_SUBAGENTS) y hasta 3 niveles de anidación (CLAUDE_CODE_MAX_SUBAGENT_SPAWN_DEPTH).
  • Claude retoma un subagente con SendMessage usando su nombre; conserva todo su historial.
  • Desde la v2.1.198, /agents ya no abre un panel: crea y edita subagentes pidiéndoselo a Claude o editando los archivos.
Lección 3.5

Construye un subagente

Un subagente es un Markdown con frontmatter YAML; el cuerpo es su system prompt. Ubicaciones, de mayor a menor prioridad: managed, flag --agents, .claude/agents/ (proyecto), ~/.claude/agents/ (personal) y plugins.

Constructor de subagentes

CampoPara qué
name, descriptionRequeridos. La descripción decide cuándo Claude delega; "use proactively" lo incentiva
tools / disallowedToolsAllowlist / denylist. Agent(worker, researcher) limita qué subagentes puede lanzar
model, effortsonnet, opus, haiku, fable, ID completo o inherit
skillsSkills precargadas completas al iniciar
memoryMemoria persistente: .claude/agent-memory/<nombre>/ (project), ~/.claude/agent-memory/ (user) o local
isolation: worktreeCorre en un worktree temporal de git
hooks, mcpServersHooks y servidores MCP solo mientras el subagente está activo
maxTurns, background, colorLímite de turnos, forzar segundo plano, color en la UI

Invócalos con lenguaje natural ("usa el subagente code-reviewer…"), con @agent-code-reviewer (garantizado) o como agente de toda la sesión: claude --agent code-reviewer. Los campos mal escritos se ignoran sin aviso; los nombres compuestos usan camelCase.

Lección 3.6

Skills: estructura e invocación

Una skill es una carpeta con un SKILL.md (frontmatter + instrucciones) y archivos de apoyo opcionales. Es la extensión más flexible: puede ser referencia (tu guía de estilo de API) o acción (/deploy corre tu checklist). Claude ve solo nombre y descripción hasta que la usa; recién entonces carga el contenido completo.

UbicaciónRutaAlcance
Empresadirectorio de managed settingsToda la organización
Personal~/.claude/skills/<nombre>/SKILL.mdTodos tus proyectos
Proyecto.claude/skills/<nombre>/SKILL.mdEste repo
Plugin<plugin>/skills/<nombre>/SKILL.mdSe invoca /plugin:skill

Ante nombres repetidos: empresa gana sobre personal, y personal sobre proyecto. El formato antiguo .claude/commands/deploy.md sigue funcionando, pero las skills son las recomendadas porque admiten archivos de apoyo.

Quién puede invocarla

FrontmatterTúClaudeDescripción en contexto
(por defecto)SíSíSiempre
disable-model-invocation: trueSíNoNo (costo cero hasta que la invoques)
user-invocable: falseNoSíSiempre
  • Usa disable-model-invocation: true para skills con efectos secundarios (deploy, commit, push): ahorras contexto y solo tú las disparas.
  • La descripción más when_to_use se trunca a 1.536 caracteres en el listado: pon el caso de uso clave primero.
  • Mantén SKILL.md bajo 500 líneas; mueve el detalle a archivos de apoyo y referéncialos para que Claude sepa cuándo leerlos.
  • Los cambios a SKILL.md aplican en vivo; una carpeta skills/ nueva requiere /reload-skills.
  • /skills lista y filtra (con t ordenas por tokens); /skill-doctor muestra qué skills cuestan contexto y cuánto se usan.
Lección 3.7

Skills avanzadas

Constructor de skills

Sustituciones

PlaceholderSe expande a
$ARGUMENTSTodo lo que escribiste tras el comando. Si no hay placeholder, se agrega ARGUMENTS: … al final
$0, $1… o $nombreArgumento por posición, o por nombre si declaras arguments. /migrar SearchBar JS TS llena $0, $1, $2
${CLAUDE_SKILL_DIR}Carpeta de la skill. Úsalo en el contenido y en allowed-tools para correr scripts propios sin prompt
${CLAUDE_PROJECT_DIR}, ${CLAUDE_SESSION_ID}Raíz del proyecto, ID de sesión

Inyección dinámica con !`comando`

Una línea !`git diff HEAD` corre antes de que Claude vea la skill y su salida reemplaza el placeholder. Si el comando falla, aborta toda la invocación: agrega || true para tolerar fallos. Los comandos pasan por tus reglas de permiso.

Más controles

  • context: fork + agent: Explore corre la skill en un subagente: el contenido se vuelve su tarea y no ve tu historial. Úsalo solo para skills con una tarea explícita.
  • paths limita la autoactivación a ciertos archivos; model y effort cambian el modelo solo para ese turno.
  • allowed-tools preaprueba herramientas solo para el turno que invoca la skill; no restringe las demás.
  • Apilar: /write-tests /fix-issue 123 carga ambas skills (hasta seis).
  • skillOverrides en settings controla la visibilidad sin editar el archivo: "on", "name-only", "user-invocable-only", "off".

Skills incluidas

/code-review, /simplify, /verify, /run, /batch, /debug, /loop, /doctor, /claude-api, /fewer-permission-prompts, /update-config y más. Si tu proyecto tiene una skill llamada verify o simplify, Claude la corre antes de cada commit (salvo cambios de docs o tests).

A fondoSkills a fondoAnatomía de SKILL.md, sustituciones en vivo y generador.→
Lección 3.8

MCP: conectar herramientas externas

El Model Context Protocol conecta a Claude Code con sistemas externos: issue trackers, bases de datos, monitoreo, Figma, Notion. Cada servidor expone herramientas que Claude puede llamar, nombradas mcp__servidor__herramienta.

Constructor de comando MCP
ScopeSe guarda enCompartido
local (default)~/.claude.json bajo la ruta del proyectoNo
project.mcp.json en la raíz del repoSí, vía git (requiere aprobación al primer uso)
user~/.claude.jsonNo, pero en todos tus proyectos

Precedencia por nombre: local → project → user → plugins → conectores de claude.ai. No se mezclan entre scopes. El separador -- divide las opciones de Claude del comando del servidor: todo lo que va después pasa intacto.

.mcp.json
{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

Se expanden ${VAR} y ${VAR:-default} en command, args, env, url y headers, así no commiteas secretos. Las entradas remotas necesitan type; sin él se interpretan como stdio y se omiten.

Lección 3.9

MCP: autenticación, límites y seguridad

  • OAuth: /mcp muestra el estado de cada servidor y lanza el flujo en el navegador; los tokens se renuevan solos. Desde la shell: claude mcp login <nombre> (con --no-browser por SSH).
  • Gestión: claude mcp list, claude mcp get notion, claude mcp remove notion. Dentro de la sesión, /mcp desactiva servidores sin borrarlos.
  • Tool search: activo por defecto. Solo los nombres de herramientas ocupan contexto; los schemas completos se cargan cuando Claude necesita una. Se desactiva con ENABLE_TOOL_SEARCH=false.
  • Límites de salida: 25.000 tokens por respuesta de herramienta por defecto (advertencia desde 10.000), ajustable con MAX_MCP_OUTPUT_TOKENS. MCP_TIMEOUT controla el arranque.
  • Llamadas largas: pasadas de 2 minutos se mueven a tareas en segundo plano.

MCP vs CLI vs skills

CLI primeroHerramientas como gh, aws, gcloud o sentry-cli son lo más eficiente en contexto: no agregan listado de herramientas.
MCPCuando no hay CLI, o necesitas autenticación gestionada por el servidor y herramientas hechas para ese sistema.
Skill + MCPMCP da la conexión; una skill enseña a usarla bien (tu schema, tus patrones de consulta).
SeguridadVerifica que confías en cada servidor antes de conectarlo. Los que traen contenido externo te exponen a prompt injection. Para bases de datos, usa un usuario de solo lectura. Las variables con nombre de credencial (como ANTHROPIC_API_KEY) se leen vacías en URLs y headers remotos, para que un .mcp.json ajeno no las exfiltre.
Lección 3.10

Sandbox de Bash

El sandbox es una barrera que el sistema operativo aplica a los comandos de shell que corre Claude y a los procesos que estos lanzan. Tú defines qué archivos y dominios pueden alcanzar. Como la barrera la impone el SO, Claude Code puede correr comandos sandboxeados sin pedirte aprobación uno por uno. Está apagado por defecto: actívalo con /sandbox.

AccesoPor defectoSe cambia con
EscrituraDirectorio de trabajo, temp por usuario y directorios agregadosfilesystem.allowWrite
LecturaCasi toda la máquina, incluidos ~/.ssh y credencialesfilesystem.denyRead
RedSin salida directa; un proxy local revisa cada host contra tu allowlist, que empieza vacíanetwork.allowedDomains
.claude/settings.json
{
  "sandbox": {
    "enabled": true,
    "filesystem": {
      "allowWrite": ["~/.kube", "/tmp/build"],
      "denyRead": ["~/"],
      "allowRead": ["."]
    }
  }
}
  • Plataformas: macOS usa Seatbelt (nada que instalar); Linux y WSL2 usan bubblewrap y socat. En Windows nativo los comandos corren sin sandbox: usa WSL2.
  • Modo auto-allow: los comandos que corren dentro del sandbox se aprueban solos. Las reglas deny, los ask por contenido (como Bash(git push *)) y los rm sobre rutas críticas siguen aplicando.
  • Escape hatch: si un comando falla dentro del sandbox, Claude puede pedir reintentarlo fuera; según tu modo, se te pregunta o lo evalúa el clasificador. excludedCommands corre ciertas herramientas siempre fuera.
  • Qué no cubre: las herramientas Read, Edit, Write y WebFetch (usan reglas de permiso), hooks, servidores MCP locales y los comandos ! que tú tipeas. Para una barrera total, corre Claude Code dentro de un contenedor o VM (dev containers).
Lección 3.11

Worktrees y sesiones paralelas

Un git worktree es un directorio de trabajo separado, con su propia rama, que comparte historial y remoto con tu checkout principal. Con cada sesión en su worktree, las ediciones de una nunca tocan los archivos de otra.

bash
# crea .claude/worktrees/feature-auth en la rama worktree-feature-auth
claude --worktree feature-auth

# en otra terminal, otra sesión aislada
claude -w bugfix-123

# worktree a partir de un pull request (comillas por el #)
claude --worktree "#1234"
  • Agrega .claude/worktrees/ a tu .gitignore.
  • Archivos ignorados: un worktree es un checkout limpio, sin tu .env. Crea .worktreeinclude (sintaxis de .gitignore) para copiarlos automáticamente.
  • Rama base: por defecto parte de la rama default del remoto. Con "worktree": {"baseRef": "head"} en settings parte de tu HEAD local.
  • Limpieza: al salir, si el worktree está limpio se borra; si tiene cambios o commits, Claude te pregunta si conservarlo.
  • También puedes pedir "trabaja en un worktree" y Claude lo crea. Los subagentes con isolation: worktree usan uno temporal.

Patrón escritor / revisor

Un contexto nuevo revisa mejor porque no está sesgado hacia código que acaba de escribir. Sesión A: "implementa un rate limiter para la API". Sesión B: "revisa el rate limiter en @src/middleware/rateLimiter.ts buscando casos borde, condiciones de carrera y consistencia con nuestros middlewares". Luego pasas el feedback a A. Lo mismo funciona con tests: una sesión los escribe y otra escribe el código que los pasa.

/batchPara cambios grandes, /batch <instrucción> investiga el código, divide el trabajo en 5 a 30 unidades independientes, te presenta un plan y, al aprobarlo, lanza un subagente por unidad, cada uno en su propio worktree.
Lección 3.12

Revisión de código integrada

Claude Code trae varias formas de revisar. Elige según profundidad y dónde quieres los hallazgos.

ComandoQué hace
/code-reviewRevisa tu rama (commits sobre el upstream más cambios sin commit) buscando bugs de correctitud. Corre como subagente en segundo plano. Alias: /review
/code-review high --fixElige effort (low reporta solo lo más seguro; hacia max amplía cobertura) y aplica los arreglos
/code-review --comment 1234Publica los hallazgos como comentarios inline en el PR
/code-review main...mi-featureApunta a una rama, un rango (HEAD~15..HEAD), un PR o una ruta
/simplifyCuatro agentes en paralelo buscan reutilización, simplificación y eficiencia, y aplican los arreglos
/security-reviewAnaliza los cambios de tu rama contra la default buscando inyección, auth y exposición de datos
/verify · /runConstruye, levanta y maneja tu app para confirmar que el cambio funciona de verdad, no solo que pasan los tests
/ultrareviewRevisión profunda multiagente en un sandbox en la nube (o /code-review ultra)
Revisión adversarialMientras más trabaja Claude sin supervisión, más importa un chequeo independiente. Un subagente revisor ve solo el diff y los criterios, no el razonamiento que produjo el cambio. Dile que reporte solo brechas que afecten correctitud o requisitos: un revisor al que le pides encontrar problemas casi siempre encuentra algunos, y perseguirlos todos lleva a sobreingeniería.

Para revisión automática de cada PR sin mantener un workflow existe Code Review, un servicio gestionado que un Owner activa para la organización (nivel Experto).

Quiz final

Quiz · Nivel Avanzado

Responde todas correctamente para aprobar