Comandos personalizados, Hooks y Subagentes: Para qué sirve cada uno
Claude Code viene con tres formas distintas de extender su comportamiento: comandos de barra personalizados, hooks y subagentes.
Se agrupan porque todos viven bajo el mismo paraguas de "personalizar Claude Code", y porque un proyecto real suele terminar usando los tres a la vez.
Pero resuelven problemas diferentes, se ejecutan en puntos distintos del flujo de trabajo y se configuran de maneras completamente diferentes.
Confundirlos es la fuente más común de confusión para un equipo que configura Claude Code por primera vez.
Resumen
- Idea central: un comando personalizado es un prompt reutilizable, un hook es un disparador automático de shell y un subagente es una instancia de Claude aislada con su propio contexto y herramientas.
- Por qué importa: elegir el punto de extensión incorrecto para una tarea o falla por completo (un hook no puede "pensar") o desperdicia esfuerzo (un subagente para algo que un comando de una línea haría).
- Conceptos clave: comando de barra, frontmatter, cuerpo del prompt, evento del ciclo de vida, PreToolUse, PostToolUse, Stop, contexto aislado, acceso a herramientas con ámbito limitado.
- Cuándo usar: comandos para solicitudes repetibles que escribes a menudo, hooks para cualquier cosa que deba suceder de forma determinista fuera del juicio de Claude, subagentes para trabajos que necesitan su propia ventana de contexto o un conjunto de herramientas más reducido.
- Limitaciones / Compensaciones: los comandos aún consumen el contexto de la sesión principal, los hooks no pueden razonar (solo ejecutan lógica de shell) y los subagentes añaden latencia y pierden acceso al contexto de ejecución del padre.
- Temas relacionados: frontmatter de comandos de barra, automatización PostToolUse, bloqueo PreToolUse, investigación paralela de subagentes.
Fundamentos
Piensa en los tres puntos de extensión como respuestas a tres preguntas diferentes.
Los comandos de barra personalizados responden a "¿cómo evito escribir la misma solicitud una y otra vez?"
Un comando es un archivo markdown con una cabecera frontmatter y un cuerpo de prompt, almacenado en un directorio de comandos de proyecto o de usuario.
Escribir /review-pr envía el prompt de ese archivo a la conversación actual exactamente como si lo hubieras escrito tú mismo.
Los hooks responden a "¿cómo hago que algo suceda siempre, sin pedirle a Claude que recuerde hacerlo?"
Un hook es un comando de shell registrado contra un evento del ciclo de vida, como antes de que se ejecute una herramienta o después de que se complete la edición de un archivo.
El sistema ejecuta el hook directamente. Claude no decide si el hook se dispara; el evento que se dispara es lo que lo activa.
Los subagentes responden a "¿cómo le doy a una pieza de trabajo su propia pizarra limpia?"
Un subagente es una instancia de Claude separada, iniciada por la sesión principal, con su propia ventana de contexto y su propia lista de herramientas permitidas.
Realiza el trabajo asignado, luego informa un resumen a la sesión que lo inició, sin haber visto nunca todo lo demás en el historial de esa sesión.
Una analogía útil: un comando es una macro guardada, un hook es un cable trampa y un subagente es un compañero de trabajo al que le entregas una carpeta sellada con instrucciones.
Mecánicas e Interacciones
Los tres puntos de extensión difieren más claramente en quién o qué decide que se ejecuten.
Un comando solo se ejecuta cuando un usuario (o otro prompt) lo invoca explícitamente por su nombre. Nada se dispara por sí solo.
Un hook se ejecuta automáticamente cada vez que ocurre su evento registrado, independientemente de qué comando o prompt activó ese evento. No tiene conciencia de la intención, solo de la carga útil del evento que recibe.
Un subagente se ejecuta cuando el Claude de la sesión principal lo inicia explícitamente, típicamente porque una tarea es grande, independiente o de lo contrario inundaría el contexto principal con detalles intermedios.
Estos tres también difieren en qué pueden ver y tocar.
El cuerpo del prompt de un comando se convierte en parte de la conversación actual, por lo que comparte el contexto completo de la sesión principal y su acceso completo a herramientas.
Un hook típicamente ejecuta un script de shell simple o un comando CLI; no tiene razonamiento de modelo propio; solo ejecuta y devuelve un estado de salida.
Un subagente obtiene una ventana de contexto aislada, inicializada solo con lo que el padre elige entregarle, y una lista de herramientas que puede limitarse desde los permisos del propio padre.
# Un hook no "entiende" la edición; solo reacciona a la carga útil del evento.
# Esta es una entrada de hook PostToolUse en settings.json, conceptualmente:
{
"PostToolUse": [
{ "matcher": "Edit", "hooks": [{ "type": "command", "command": "npx prettier --write \"$FILE_PATH\"" }] }
]
}Ese fragmento es una conexión de ciclo de vida, no un prompt. Nada en él le pide a Claude que decida si formatear el archivo; el formateo simplemente ocurre cada vez que se dispara un evento de edición.
Los comandos y subagentes, por el contrario, ambos pasan por el modelo, que es por lo que ambos pueden razonar, hacer preguntas de seguimiento internamente y producir juicios que un hook nunca podría.
Consideraciones Avanzadas y Aplicaciones
En la práctica, los tres puntos de extensión rara vez se usan de forma aislada. Un comando puede instruir a Claude para que inicie varios subagentes. Un hook PreToolUse puede bloquear una de las ediciones de esos subagentes tan fácilmente como bloquea las de la sesión principal. Los eventos del ciclo de vida a los que escucha un hook no se preocupan por qué capa del sistema generó la llamada a la herramienta.
Esta componibilidad es también donde los equipos tienen problemas. Un comando que siempre inicia tres subagentes para una tarea que solo necesitaba uno desperdicia latencia y tokens. Un hook escrito para "ayudar" autocomprometiendo en cada evento Stop puede confirmar silenciosamente trabajo a medio terminar si se dispara en el Stop de un subagente, no solo en el de la sesión principal. Comprender los límites en este artículo es lo que previene esos errores a posteriori.
| Punto de Extensión | Desencadenado Por | Se Ejecuta Dónde | Mejor Ajuste |
|---|---|---|---|
| Comando de barra personalizado | Invocación explícita /nombre | Contexto de la sesión principal | Solicitudes repetibles y reutilizables |
| Hook | Un evento de ciclo de vida registrado | Shell, fuera del modelo | Efectos secundarios deterministas: formatear, registrar, bloquear |
| Subagente | Claude iniciándolo a mitad de tarea | Su propio contexto aislado | Trabajo grande, independiente o paralelo |
También hay una dimensión de gobernanza. Los comandos viven en el control de versiones como markdown plano, por lo que un equipo puede revisarlos y compartirlos como cualquier otro archivo fuente. Los hooks viven en settings.json y, dado que ejecutan comandos de shell arbitrarios, merecen el mismo escrutinio que cualquier otro ejecutable registrado en un repositorio. Las definiciones de subagentes pueden restringir el acceso a herramientas por rol, lo que es un límite de seguridad real, no solo una conveniencia organizativa, ya que un subagente con ámbito de herramientas de solo lectura no puede editar archivos incluso si el prompt intenta convencerlo de hacerlo.
Conceptos Erróneos Comunes
- "Un hook es solo un comando que se ejecuta a sí mismo." Un hook no tiene prompt ni razonamiento de modelo asociado; es un disparador de shell conectado a un evento, más parecido a un hook pre-commit de git que a un comando de barra.
- "Los subagentes comparten el contexto de la sesión principal para ahorrar tokens." Lo contrario es cierto; el aislamiento es el propósito principal, y un subagente solo recibe lo que el padre incluye explícitamente en su prompt de tarea.
- "Los comandos pueden bloquear o vetar una acción." Solo los hooks (específicamente PreToolUse) pueden rechazar una llamada a herramienta antes de que ocurra; un comando solo puede dar forma a lo que se solicita en primer lugar.
- "Cualquiera de los tres puede reemplazar a los otros." Cada uno cubre un mecanismo diferente (invocación, automatización, aislamiento); un flujo de trabajo que realmente necesita bloqueo determinista no lo obtendrá de un comando, sin importar cuán cuidadosamente esté redactado el prompt.
Preguntas Frecuentes
¿Cuál es la forma más sencilla de recordar la diferencia entre los tres?
- Comando: algo que pides por nombre.
- Hook: algo que sucede automáticamente en un evento.
- Subagente: otra persona que realiza una parte del trabajo en su propio espacio.
¿Puede un comando de barra personalizado iniciar un subagente?
Sí. El cuerpo del prompt de un comando puede instruir a Claude para que delegue parte de la tarea a uno o más subagentes, de la misma manera que lo haría una solicitud escrita.
¿Los hooks requieren que Claude esté "pensando" cuando se ejecutan?
No. Los hooks son comandos de shell ejecutados por el sistema en respuesta a un evento; se ejecutan independientemente de lo que Claude esté razonando en ese momento.
¿Por qué usaría un subagente en lugar de simplemente preguntar en la sesión principal?
Para evitar que la ventana de contexto de la sesión principal se llene con detalles de investigación o exploración intermedios que solo importan para una subtarea, no para el resto de la conversación.
¿Puede un hook ver lo que Claude está a punto de hacer antes de que suceda?
Sí, específicamente para los hooks PreToolUse. Reciben la llamada a herramienta propuesta como entrada y pueden aprobarla, modificar el resultado o bloquearla antes de que la herramienta se ejecute.
¿Los subagentes y la sesión principal de Claude Code ejecutan modelos diferentes?
No necesariamente. Un subagente puede configurarse para usar el mismo modelo que la sesión padre o uno diferente; la característica distintiva es el contexto aislado y el ámbito de las herramientas, no la elección del modelo.
¿Dónde viven los comandos personalizados en el disco?
Como archivos markdown con una cabecera frontmatter y un cuerpo de prompt, en un directorio de comandos con ámbito de proyecto o de usuario, para que puedan ser controlados por versiones junto con el resto de un repositorio.
¿Es un hook la herramienta adecuada para "ejecutar siempre el linter después de cada edición"?
Sí. Ese es un efecto secundario determinista e incondicional ligado a un evento (una edición de archivo), que es exactamente para lo que está diseñado un hook PostToolUse.
¿Es un hook la herramienta adecuada para "decidir si esta refactorización es una buena idea"?
No. Eso requiere juicio, que solo el prompt de un comando o el razonamiento de un subagente pueden proporcionar; un hook solo puede ejecutar lógica de shell fija contra el evento que recibe.
¿Qué sucede con el contexto de un subagente una vez que termina?
Informa un resumen a la sesión padre y su contexto completo se descarta; el padre nunca ve la exploración intermedia en bruto del subagente, solo lo que eligió informar.
¿Pueden múltiples hooks activarse en el mismo evento?
Sí. Un solo evento de ciclo de vida, como PostToolUse, puede tener múltiples comandos de hook registrados contra él, y se ejecutan en el orden en que están configurados.
¿Necesito los tres puntos de extensión para usar Claude Code de manera efectiva?
No. Muchos proyectos usan solo comandos personalizados durante mucho tiempo antes de que surja una necesidad real de automatización determinista (hooks) o aislamiento de contexto (subagentes).
Relacionados
- Fundamentos de Comandos Personalizados y Subagentes - un primer comando y subagente prácticos.
- Escribir tu primer comando de barra personalizado con Frontmatter Markdown - el formato de archivo detrás de cada comando.
- Eventos de Hook Comunes y Cuándo Usar Cada Uno - el conjunto completo de eventos de ciclo de vida a los que los hooks pueden adjuntarse.
- Cómo los Subagentes Obtienen su Propio Contexto y Herramientas - el mecanismo de aislamiento explicado en profundidad.
Versiones de Stack: Escrito contra la línea de modelos de Claude actual a partir de ~junio de 2026 - Claude Fable 5, Claude Opus 4.8, Claude Sonnet 5 (el predeterminado) y Claude Haiku 4.5. Los nombres de los modelos, los precios y las características del producto cambian rápidamente; verifica los detalles actuales en platform.claude.com/docs antes de confiar en ellos.