Ampliar Claude Code: CLAUDE.md, hooks, subagents y MCP

En los cinco capítulos anteriores has instalado Claude Code, le has dado instrucciones, has salido de los atascos y has diseñado los permisos. Este capítulo va de modificar la herramienta en sí. Con las extensiones no basta con aprenderse los nombres. Lo que sirve es una tabla de correspondencias que responda a «cuál de ellas resuelve la molestia que tengo ahora».

El mapa para elegir: lo deciden cuatro preguntas

Hay seis extensiones, pero solo hay cuatro cosas que pensar: ¿basta con pedirlo? ¿quiero que se cumpla siempre? ¿quiero separarlo en otro contexto? ¿quiero conectarme al exterior? Preguntándotelo en ese orden, la respuesta suele quedar unívoca.

¿Basta con pedirlo?

Si que se escape de vez en cuando no es grave, con las palabras basta. → CLAUDE.md (premisas generales) / Skills (procedimientos de un trabajo concreto)

¿Quiero que se cumpla siempre?

Si que se escape una sola vez ya es un problema, detenlo con un mecanismo. → hooks. Se ejecutan cuando la configuración habilitada coincide con el evento y sus condiciones.

¿Quiero separarlo en otro contexto?

Si no quieres enterrar el hilo principal bajo un montón de salida, que lo haga fuera y te devuelva solo la conclusión. → subagents

¿Quiero conectarme al exterior?

Si necesitas información que la IA no tiene forma de conocer (el valor actual de una base de datos, el contenido del gestor de incidencias). → MCP

La quinta pregunta es «¿voy a repartir esto a otras personas?»: si es que sí, plugins. Lo que más se confunde son Q1 y Q2, es decir, CLAUDE.md, Skills y hooks. Los tres parecen lo mismo, pero se diferencian en cuándo se leen y quién los ejecuta.

CLAUDE.md: distingue la carga del cumplimiento

CLAUDE.md aporta contexto del proyecto en cada sesión cuando se encuentra en una ubicación que se carga. Usa ~/.claude/CLAUDE.md para las instrucciones comunes a varios proyectos. Contiene instrucciones en texto, no una configuración que imponga permisos de operación.

Si el agente dice que ha leído el archivo pero no lo cumple, comprueba estas tres cuestiones por separado.

¿Se ha cargado? Mira si CLAUDE.md y las reglas aparecen en Memory files de /context. La ubicación de inicio y las exclusiones afectan a los archivos incluidos. AGENTS.md cargado directamente no aparece en esta lista, por lo que su ausencia no demuestra que no se haya leído
¿Se ha recuperado tras la compactación? El CLAUDE.md de la raíz del proyecto se vuelve a leer del disco y se reinserta después de /compact. Los CLAUDE.md de subdirectorios y las reglas por ruta se recargan al leer archivos coincidentes. Las decisiones conservadas únicamente en la conversación se gestionan de otra manera
¿Ha influido en la acción? Aunque se haya cargado, comprueba por separado las reglas vagas y los conflictos entre instrucciones. No des por hecho que siempre gana la instrucción más reciente. Especifica el alcance y las condiciones de excepción

La recomendación oficial es menos de 200 líneas por archivo CLAUDE.md. No es un límite de carga ni un umbral que garantice el cumplimiento. Conserva las reglas necesarias en cada sesión y separa los detalles indicando cuándo deben leerse. Importar todo mediante @path no reduce el contexto inicial. Usa Skills para procedimientos ocasionales y reglas por ruta para instrucciones limitadas a ciertos archivos.

Esto se basa en la documentación oficial de memoria. Para ver ejemplos prácticos de cómo distinguir cada caso y las diferencias entre herramientas, consulta cómo investigar por qué los agentes de IA ignoran las reglas.

«Lo he leído» no demuestra cumplimiento. Comprueba por separado la visualización de carga, los diffs y los resultados de las pruebas. Traslada las condiciones comprobables de forma mecánica a hooks o CI, como se explica a continuación, e informa de las áreas que queden sin verificar.

hooks: ejecutar controles al cumplirse las condiciones

Una instrucción escrita como «no reescribas .env» no garantiza una tasa de cumplimiento. Si necesitas comprobar una condición y bloquear una operación antes de ejecutarla, considera los permisos y los hooks.

Este apartado trata los hooks de tipo command, que ejecutan comandos de shell. Cuando la configuración habilitada coincide con el evento y sus condiciones, los lanza el propio Claude Code. No necesitas que el modelo recuerde ejecutarlos. Sin embargo, no se ejecutan si están deshabilitados en la configuración o si la operación sigue una vía no cubierta. Encontrarás una visión general en qué son los hooks de Claude Code. Los siguientes son nueve eventos representativos, no una lista exhaustiva.

SessionStart        al iniciar o reanudar
UserPromptSubmit    justo después de enviar               [puede bloquear]
PreToolUse          justo antes de una herramienta = portero  [puede bloquear]
PostToolUse         tras el éxito de una herramienta = formateo  (no deshace la acción completada)
Notification        esperando entrada o aprobación
Stop                final de una respuesta                [puede bloquear]
SubagentStop        el subagente ha terminado             [puede bloquear]
SessionEnd          fin de la sesión
PreCompact          antes de la compresión                [puede bloquear]

Lo que puede bloquearse depende del evento. Bloquear una herramienta antes de ejecutarla no es lo mismo que impedir que termine una respuesta para continuar trabajando. Rechazar operaciones peligrosas en PreToolUse y formatear automáticamente en PostToolUse son dos puntos de partida habituales. La configuración va bajo la clave "hooks" de settings.json. La ubicación del archivo determina el alcance (~/.claude/ = usuario, .claude/ = compartido, settings.local.json = personal).

Ahora convirtamos en un mecanismo el «no reescribas .env» del principio. Es el ejemplo de la guía oficial para bloquear la edición de archivos protegidos, limitado a .env. Necesitas dos cosas: la configuración y un script.

① .claude/settings.json: ejecuta el script justo antes de llamar a Edit o Write.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/protect-env.sh"
          }
        ]
      }
    ]
  }
}

② .claude/hooks/protect-env.sh: bloquea la edición si el nombre del archivo de destino empieza por .env (incluidos .env.local y similares). En macOS y Linux, dale permiso de ejecución con chmod +x .claude/hooks/protect-env.sh.

#!/bin/bash
# .claude/hooks/protect-env.sh
command -v jq >/dev/null || { echo "No se encontró jq, así que se bloqueó la edición" >&2; exit 2; }

FILE_PATH=$(jq -r '.tool_input.file_path // empty')
FILE_PATH="${FILE_PATH//\\//}"   # convierte las \ de Windows en /

if [[ "${FILE_PATH##*/}" == .env* ]]; then
  echo "Blocked: $FILE_PATH es un archivo .env, así que no se editará" >&2
  exit 2
fi
exit 0

La estructura es nombre del evento → array de condiciones de coincidencia y comandos. matcher indica los nombres de herramientas: "Edit|Write" coincide con Edit o con Write (si lo omites, con todas). El hook recibe JSON por la entrada estándar, y en Edit y Write tool_input.file_path contiene la ruta absoluta del archivo que se va a editar. En Windows, el separador de esa ruta es \, así que el script lo convierte en / antes de comparar. Si lo detienes con el código de salida 2, el texto de la salida de error estándar llega a Claude como motivo del rechazo, y Claude lo lee y busca otra forma de hacerlo. 1 se trata como un error no bloqueante y la operación continúa, así que usa 2 cuando quieras detenerla. 0 significa que no hay objeciones y se pasa a la comprobación normal de permisos.

El script usa bash y jq (el ejemplo de la guía oficial también da por hecho jq). En Windows, los hooks se ejecutan en Git Bash y, si Git Bash no está instalado, en PowerShell, así que este ejemplo necesita Git Bash. Para no dejar pasar ediciones cuando falta jq, el script lo comprueba en su primera instrucción y, si no está, bloquea la edición.

Los hooks pueden endurecer las restricciones, pero no relajarlas. Aunque devuelvan una autorización, lo único que hacen es ahorrar la pregunta, y las reglas de denegación tienen siempre prioridad. Como el rechazo desde PreToolUse funciona incluso en el modo que se salta todas las aprobaciones, sirve de suelo para lo que aflojaste en el capítulo 5.

Se prueba igual que en la guía oficial. Pide a Claude «añade una línea de comentario a .env»: la edición se detiene antes de ejecutarse y el texto Blocked: vuelve a Claude. Comprueba también que los archivos que no son .env se siguen pudiendo editar como antes. Si escribes mal la ruta del script, solo aparece el aviso Failed with non-blocking status code y la puerta queda abierta, así que presta atención también a ese aviso. Además, este ejemplo solo detiene las herramientas Edit y Write; las modificaciones mediante comandos de Bash o PowerShell siguen otra vía. Amplía el alcance según lo que quieras bloquear. Los formatos de salida y las diferencias entre eventos se describen en la guía oficial de Hooks.

Ten presente el coste: los hooks de tipo command ejecutan automáticamente comandos de shell con tus permisos de usuario y pueden modificar o eliminar cualquier archivo al que tenga acceso tu cuenta. La documentación oficial también pide leer y probar todos los comandos antes de añadirlos. Configura solo comandos fiables y valida las entradas. Los cambios hechos editando directamente los archivos de configuración normalmente se aplican de forma automática. Revisa el registro con /hooks y, si no se ha aplicado, revisa el JSON y la ubicación del archivo antes de reiniciar la sesión.

subagents: delegar en un contexto aparte

La salida completa de las pruebas y los logs enormes pueden llenar el contexto de grandes cantidades de texto que solo pensabas ojear, desplazando premisas importantes. Los subagentes realizan ese trabajo en un contexto separado y devuelven un resumen de la conclusión. Normalmente tienen su propio contexto, instrucciones y permisos de herramientas, así que el agente principal debe transmitir explícitamente la información necesaria. Una ejecución que bifurca la conversación y hereda el historial del agente principal es una excepción; esto es distinto de context: fork en una skill. Como el informe es un resumen, pide que también incluya las pruebas necesarias y las cuestiones pendientes.

Separar compensa: investigaciones amplias / comprobaciones que generan mucha salida / tareas autocontenidas de las que solo necesitas la conclusión
Separar sale caro: procesos secuenciales / idas y venidas frecuentes / trabajos en paralelo que tocan el mismo archivo / correcciones que se resuelven en uno o dos pasos

Como es una función estándar, se puede usar sin configurar nada. Si quieres añadir definiciones, van en .claude/agents/<nombre>.md (para uso común, en ~/.claude/agents/), con name, description, tools y model escritos en el frontmatter YAML. Se gestionan con /agents y se invocan con @agent-<nombre>. Empieza por los estándar de exploración, de planificación y de uso general.

La clave de la invocación es el description. El agente principal decide si delega mirando eso, de modo que una descripción ambigua hace menos probable la selección automática. Concreta qué hace y cuándo usarlo. La misma trampa existe en las Skills.

Los Agent Teams, fáciles de confundir, son el mecanismo por el que varias sesiones independientes se coordinan mediante una lista de tareas compartida. Son una opción experimental de activación explícita y están desactivados por defecto (CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1). Como levantan instancias distintas, el consumo de tokens es alto, y tampoco se pueden anidar. Las diferencias las comparamos en las diferencias entre subagents y Agent Teams. Ante la duda, una sola sesión o subagents.

Skills: convertir los procedimientos en activos

Frente a las rutinas del tipo «esto siempre se hace así», lo bueno de las Skills es que solo se abren cuando hacen falta. En realidad son una carpeta articulada alrededor de un SKILL.md. Arriba van name y description, debajo el procedimiento en Markdown, y también puedes incluir un reference/ o un scripts/. Basta con colocarla en .claude/skills/ (del proyecto) o en ~/.claude/skills/ (común) para que se reconozca.

La idea central es la divulgación progresiva. Normalmente, una lista de nombres y descripciones de skills entra en el contexto, mientras que el cuerpo se carga mediante selección automática o una invocación explícita con /skill-name. Los materiales de apoyo se leen cuando hacen falta. La lista de descripciones también consume contexto; si hay muchas skills, las descripciones pueden acortarse u omitirse para ajustarse al presupuesto. Escribe un description concreto y verifica por separado que la skill se haya invocado y que su procedimiento haya producido los resultados esperados. Consulta qué son las Claude Agent Skills para aprender a redactarlas.

En una línea: CLAUDE.md = premisas que se cargan habitualmente; Skills = procedimientos abiertos mediante selección automática o invocación explícita; hooks de tipo command = procesos activados por los eventos y condiciones configurados.

MCP: alcanzar los sistemas de fuera

MCP (Model Context Protocol) es un estándar para acceder a datos y operaciones externos, como valores actuales de una base de datos o incidencias de un gestor de tareas. Estos son dos métodos habituales de conexión. Diagnostica los problemas combinando el método de conexión con los detalles del error.

Local (stdio): el servidor se inicia como proceso hijo en tu equipo. Las pistas son la ruta del ejecutable, las variables de entorno necesarias y la salida de error del servidor
Remoto (HTTP): te conectas a un servidor mediante una URL. Las pistas son la URL, la red, los errores del servidor y las credenciales

Empieza por el estado y los detalles de /mcp. failed puede aparecer en servidores locales y remotos. Si Issue: en claude mcp get <name> incluye un código HTTP o el cuerpo del error, léelo también. needs authentication orienta hacia la autenticación; pending approval, hacia la revisión de la aprobación de un servidor del proyecto. Si se rechaza una cabecera fija Authorization con 401/403 durante la conexión, el estado es failed aunque el problema sea de autenticación. Las soluciones se recogen en Error de conexión MCP en Claude Code: causas y soluciones.

Coloca el archivo compartido .mcp.json en la raíz del proyecto. Utiliza el env de cada servidor para las variables enviadas a un servidor stdio; para autenticar HTTP, usa OAuth o headers, según el servicio. No escribas las claves reales directamente en archivos compartidos; referencia una variable como ${API_KEY}. Algunos nombres de variables, incluidas las credenciales del propio Claude Code, se resuelven como cadenas vacías en URL y cabeceras remotas; los detalles están en las reglas oficiales de expansión.

Las definiciones de herramientas se cargan bajo demanda de forma predeterminada. En una configuración habitual con búsqueda de herramientas, solo entran inicialmente en el contexto los nombres de las herramientas y las descripciones de los servidores. Las definiciones se cargan por adelantado cuando la búsqueda está desactivada, el entorno no es compatible o el servidor usa alwaysLoad, entre otros casos. Los resultados también consumen contexto: comprueba el uso real con /context y desactiva los servidores que no uses.

plugins: empaquetar un conjunto y repartirlo

Los plugins permiten agrupar skills, definiciones de subagentes, hooks y configuración MCP para distribuirlos. Si incluyes un manifiesto de plugin, colócalo en .claude-plugin/plugin.json. La estructura estándar sitúa skills/, agents/, hooks/hooks.json y .mcp.json en la raíz del propio plugin. No los pongas dentro de .claude-plugin/. Un plugin que solo utilice la estructura estándar puede omitir el manifiesto.

/plugin marketplace add owner/repo   ← registrar el catálogo
/plugin install name@marketplace     ← instalar desde ahí uno por uno
/plugin list                         ← listar plugins instalados mediante marketplaces

Estos son los pasos básicos para instalar mediante un marketplace. Registrar un catálogo no instala plugins por sí solo. /plugin list enumera los plugins instalados por esta vía, no todos los disponibles mediante otros mecanismos, como directorios de skills o sincronización. Los ámbitos son user (todos tus proyectos), project (configuración compartida) y local (solo tú en este proyecto). Incluso con project, cada integrante debe instalar los plugins de fuentes externas. El ámbito managed se administra de forma centralizada y restringe los cambios de configuración de los usuarios. Para crear los tuyos, consulta Plugins y Marketplace de Claude Code: usar, crear y publicar.

Los plugins pueden ejecutar código arbitrario con tus privilegios, advierte la documentación oficial. Los elementos del catálogo comunitario pasan por la validación automática y la revisión de seguridad de Anthropic, pero eso no garantiza que se comporten como esperas. Comprueba el editor, el código incluido y los servidores MCP. El diseño de permisos del capítulo 5 también se aplica aquí al código ajeno.

Por dónde empezar: una palabra sobre el orden

Hemos enumerado seis, pero no hace falta instalarlas todas. Si las añades sin tener un problema que resolver, lo único que aumenta es la complejidad de la configuración. El orden va a partir del síntoma.

Estás dando siempre la misma explicación → CLAUDE.md. Si es solo para un trabajo concreto, a Skills
Lo has escrito y no se cumple → revisa la carga, el alcance y los conflictos. Lleva las condiciones comprobables de forma mecánica a hooks
El contexto se llena enseguida → las investigaciones pesadas, a subagents; y desactiva los MCP que no uses
La IA no llega a cierta información → MCP. Conecta de uno en uno y pasa al siguiente cuando veas que funciona
Quieres repartir la misma configuración → plugins. Empaqueta solo lo que ya usas tú
No tienes ningún problema concreto → no instales nada. Ese es el mejor estado posible

La última línea no es una broma. Las extensiones también aumentan las causas de atasco: es muy habitual que la raíz de un «Claude Code está raro» sea una capa que añadiste tú. Por eso el diagnóstico del capítulo 4 va primero.

Resumen

El criterio de elección son cuatro preguntas: ¿basta con pedirlo? (CLAUDE.md, Skills) / ¿quiero que se cumpla siempre? (hooks) / ¿quiero separarlo en otro contexto? (subagents) / ¿quiero conectarme al exterior? (MCP). Para repartirlo, plugins
CLAUDE.md contiene instrucciones persistentes. El archivo raíz se reinserta tras la compactación. Acortarlo no garantiza el cumplimiento; comprueba por separado la carga y el comportamiento
Los hooks de tipo command los ejecuta Claude Code cuando coinciden las condiciones configuradas. Verifica las vías de ejecución y el comportamiento de bloqueo; un hook posterior no puede deshacer una operación completada
Los subagents trabajan en otro contexto y solo devuelven el resumen. No sirven para procesos secuenciales ni para idas y venidas frecuentes
Las Skills usan la divulgación progresiva y abren su contenido cuando hace falta. Escribe descripciones concretas para la selección automática y verifica los resultados del procedimiento incluso después de invocarlas explícitamente
MCP es un estándar de acceso externo. Diagnostica combinando el estado de /mcp con el método de conexión y los detalles del error
Los plugins son la caja de distribución. Como el código de otra persona corre con tus permisos, comprueba la procedencia
El orden en el que añadirlas va a partir del síntoma. De una en una, y solo cuando surja el problema

La comparación de las herramientas en sí para elegir entre ellas está en el capítulo 6, «Ampliar capacidades con las extensiones», del curso de coding con IA.

Cuanto más lo amplías, más consume. Para terminar, hablaremos de cómo gestionarlo para usarlo mucho tiempo. Pasa al capítulo 7, «Coste y límites».