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.
//
Busca en todas las páginas de la documentación
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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.
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).
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.
Revisado por Chris St. John·Última actualización: 15 jul 2026