Skills, comandos, hooks y subagentes

En el módulo 12 le enseñaste tu proyecto a Claude Code con un CLAUDE.md, y en el 13 aprendiste a planear, dar permisos y trabajar con Git. Si ya llevas unas cuantas sesiones, habrás notado dos cosas: que repites las mismas instrucciones ("revisa que no queden guiones largos", "corre las pruebas antes de terminar") y que algunas reglas, por mucho que las escribas, a veces no se cumplen.

Este módulo presenta las piezas con que Claude Code resuelve eso: skills (y los comandos slash, que hoy son lo mismo), hooks y subagentes, más los plugins para empaquetarlos. Lo importante no es la lista de archivos sino la regla para decidir cuál usar. Todo está verificado contra la documentación oficial de Claude Code a octubre de 2026.

¿Cuándo uso CLAUDE.md, un skill, un hook o un subagente?

Las cuatro herramientas responden a cuatro preguntas distintas sobre una instrucción. La regla de decisión:

1. 1Es algo que quieres que Claude tenga en cuenta siempre (cómo está organizado el proyecto, qué tono usas, qué no tocar): va en el CLAUDE.md del módulo 12. Es contexto que se lee al iniciar cada sesión; el modelo lo considera, pero decide con criterio.
2. 2Es un procedimiento repetible (publicar un artículo, revisar un pull request, preparar la factura del mes): se vuelve un skill. Se carga solo cuando hace falta y lo puedes invocar con un comando slash.
3. 3Es una regla que no puede fallar nunca (formatear cada archivo editado, no tocar el archivo de contraseñas): se vuelve un hook. No es una instrucción al modelo sino un comando que Claude Code ejecuta sí o sí.
4. 4Es una tarea autocontenida que necesita su propio contexto o sus propias herramientas (investigar una carpeta grande, revisar código, escribir una pieza en paralelo): se vuelve un subagente.
5. 5Es un conjunto de las anteriores que quieres compartir con tu equipo o entre proyectos: se empaqueta como plugin.

En el modelo mental del curso: CLAUDE.md es el manual de inducción del empleado nuevo; un skill, un procedimiento escrito; un hook, la cerradura de la puerta; un subagente, el colega especialista al que le delegas un encargo.

¿Qué es un skill y cómo se escribe?

Un skill es, en su versión mínima, un solo archivo llamado SKILL.md dentro de una carpeta con el nombre del skill. Tiene dos partes: un encabezado corto (en formato YAML, entre dos líneas de tres guiones) con el nombre y una descripción de qué hace y cuándo usarlo, y debajo las instrucciones en texto normal, como para un colega.

Dónde lo guardas decide quién lo ve. En .claude/skills/nombre-del-skill/SKILL.md dentro del proyecto, lo ve cualquiera que trabaje en ese repositorio (haz commit para que el equipo lo reciba). En ~/.claude/skills/ de tu computador, lo tienes en todos tus proyectos.

Hay dos formas de activarlo. La automática: Claude Code tiene en contexto, en todo momento, el nombre y la descripción de cada skill disponible, y cuando una tarea coincide carga el contenido completo. La manual: escribes /nombre-del-skill en la terminal, con argumentos si los acepta ($ARGUMENTS en el texto del skill se reemplaza por lo que escribiste después del nombre). Por eso la descripción es el campo que más vale cuidar: es lo único que el modelo lee para decidir si el skill aplica.

Un ejemplo: un skill "publicar-articulo" para el blog. Descripción: "Lista de verificación antes de publicar un artículo; úsalo cuando un borrador esté listo para salir". Instrucciones: 1) confirmar que existen las dos versiones, español e inglés, y que la inglesa no es traducción literal; 2) abrir cada fuente listada y comprobar que diga lo que el texto afirma; 3) buscar guiones largos, filler y cifras sin fuente; 4) correr las pruebas del sitio; 5) devolver un informe de qué se corrigió y qué queda para revisión humana. Un procedimiento que antes repetías de memoria, escrito una vez.

Cuatro detalles del encabezado:

• disable-model-invocation: true hace que solo tú puedas invocarlo; útil para acciones con consecuencias, como desplegar.
• allowed-tools preaprueba herramientas durante el turno en que corre el skill, para que no te pida permiso por cada paso.
• context: fork corre el skill en un subagente, con contexto aparte; enseguida vemos por qué importa.
• La carpeta puede tener archivos de apoyo (una plantilla, un script, una referencia larga) que solo se cargan si hacen falta. La documentación aconseja mantener el SKILL.md por debajo de 500 líneas.

¿Y los comandos slash? Hasta hace poco había dos mecanismos: skills y "comandos personalizados" en la carpeta .claude/commands/. A octubre de 2026, la documentación dice que los comandos personalizados se fusionaron con los skills: un archivo .claude/commands/deploy.md y un skill en .claude/skills/deploy/SKILL.md crean el mismo /deploy y funcionan igual. Los archivos viejos siguen sirviendo, pero para trabajo nuevo recomienda el skill. Aparte quedan los comandos integrados de Claude Code (/help, /init, /compact, /hooks, /agents, /plugin), que no escribes tú.

¿Qué es un hook y por qué le gana a "por favor acuérdate"?

Un hook es un comando de la terminal que Claude Code ejecuta solo, en un momento fijo de su ciclo de vida. La documentación lo describe con una palabra: determinista. Ciertas acciones ocurren siempre, en vez de depender de que el modelo decida hacerlas. Los momentos (eventos) tienen nombre: SessionStart al empezar una sesión, PreToolUse antes de que el agente use una herramienta (y puede bloquearla), PostToolUse después de que la usó con éxito, Stop cuando termina de responder, entre otros.

Se configuran en un archivo de ajustes: .claude/settings.json en el proyecto (se comparte con el repositorio), ~/.claude/settings.json en tu computador (todos tus proyectos) o .claude/settings.local.json (personal, solo ese proyecto). Cada hook dice a qué evento responde, con qué filtro (por ejemplo, solo las herramientas Edit y Write) y qué comando correr. Con /hooks ves todos los configurados.

Dos ejemplos de la propia documentación que sirven en cualquier negocio:

• Formatear cada archivo editado. Un hook PostToolUse con filtro "Edit|Write" que toma la ruta del archivo que Claude acaba de cambiar y le corre el formateador del proyecto (Prettier, en el ejemplo oficial). Resultado: nunca más un commit con formato distinto, sin pedírselo a nadie.
• Bloquear ediciones a archivos protegidos. Un hook PreToolUse, también sobre Edit y Write, que ejecuta un pequeño script: si la ruta contiene .env (donde suelen vivir contraseñas y claves), package-lock.json o la carpeta .git/, el script escribe un mensaje "Blocked" y termina con código de salida 2. Ese código le dice a Claude Code que bloquee la acción, y el mensaje le llega al modelo para que ajuste su plan. En tu negocio, la lista puede incluir la carpeta de contratos firmados o el archivo de precios.

Por qué esto le gana a una frase en CLAUDE.md: el CLAUDE.md es contexto. El modelo lo lee y casi siempre lo respeta, pero en una sesión larga, con la ventana de contexto llena, "casi siempre" no es "siempre". Un hook no se lee ni se interpreta: se ejecuta. Es la diferencia entre un letrero de "no entrar" y una puerta con llave. La regla del módulo 9 (confiar, pero verificar) aquí se vuelve código: las verificaciones que no pueden fallar no se le piden al modelo, se le imponen al proceso.

¿Qué es un subagente y cuándo vale la pena?

Un subagente es un asistente especializado al que el agente principal le delega una tarea. Según la documentación, cada uno corre en su propia ventana de contexto, con su propio prompt de sistema, acceso a herramientas específicas y permisos independientes; opcionalmente, con un modelo distinto (uno rápido y económico para buscar, uno más capaz para escribir). Cuando termina, devuelve un resumen a la conversación principal, no todo lo que leyó.

Se define en un archivo Markdown con encabezado YAML, igual que un skill, pero en otra carpeta: .claude/agents/ en el proyecto o ~/.claude/agents/ para todos tus proyectos. Solo dos campos son obligatorios: name y description (de nuevo, lo que Claude usa para decidir cuándo delegarle). Los opcionales más útiles: tools, las herramientas que puede usar; model; permissionMode; y skills, los que se le cargan al arrancar. Debajo del encabezado va el prompt de sistema: quién es, qué hace, qué formato devuelve. El comando /agents muestra los que tienes.

Claude Code trae algunos integrados, como Explore (solo lectura, para buscar en un repositorio rápido) y Plan (investigación en modo plan). Puedes delegar de tres formas: dejando que Claude lo haga solo cuando la tarea coincide con la descripción, pidiéndolo en lenguaje natural ("usa el subagente revisor para mirar los cambios") o mencionándolo con @ para garantizar que corra. Puede trabajar en primer plano (la conversación espera) o en segundo plano, mientras tú sigues con otra cosa.

Cuándo ayudan, según la documentación:

• La tarea produce mucho texto que no necesitas en tu contexto. Investigar cincuenta archivos para responder una pregunta: el subagente lee todo y te devuelve tres párrafos.
• Necesitas restringir herramientas o permisos. Un revisor que solo puede leer no va a "arreglar" nada por su cuenta.
• El trabajo es autocontenido y se puede resumir. Escribir una pieza (un artículo, un informe, un módulo de un curso) a partir de un brief claro, mientras tú haces otra cosa.

Cuándo estorban: cuando la tarea necesita ida y vuelta contigo, cuando las fases comparten mucho contexto o cuando importa la latencia. Un subagente nuevo arranca con contexto vacío: no vio tu conversación ni los archivos que ya leíste, así que Claude le escribe un mensaje de delegación y él vuelve a orientarse, gastando sus propios tokens (que cuentan contra el límite de tu plan). La regla: un subagente por tarea con nombre, entrada clara y salida resumible; no uno "por si acaso". Coordinar varios a la vez, con revisión cruzada, es el tema del módulo 18, sobre orquestación.

Esta es una tarea que repito en Claude Code y quiero convertirla en un skill:

[DESCRIBE LA TAREA PASO A PASO, COMO SE LA EXPLICARÍAS A UN COLEGA NUEVO]

Criterios de que quedó bien hecha: [CRITERIOS]
Lo que nunca debe hacer: [LÍMITES]

Crea la carpeta .claude/skills/[NOMBRE-DEL-SKILL]/ con un SKILL.md que tenga:
1. Un encabezado YAML con name y una description de una o dos frases que diga qué hace y cuándo usarlo (Claude la usa para decidir si cargar el skill).
2. Las instrucciones como pasos numerados, con los criterios y los límites.
3. Al final, el formato exacto en que debe entregar el resultado.

Si la tarea tiene consecuencias (desplegar, enviar, borrar), agrega disable-model-invocation: true para que solo yo pueda invocarlo. Muéstrame el archivo antes de crearlo.

Quiero un subagente de Claude Code para esta tarea: [TAREA].

Contexto del negocio: [DOS O TRES LÍNEAS]
Entrada que recibe: [QUÉ LE VOY A PASAR]
Salida que espero: [FORMATO EXACTO DEL RESULTADO]
Lo que no debe hacer: [LÍMITES, POR EJEMPLO: NO EDITAR ARCHIVOS, NO INVENTAR CIFRAS]

Escribe el archivo .claude/agents/[NOMBRE].md con:
- name y description (la description debe decir para qué sirve y para qué NO, porque Claude la usa para decidir cuándo delegarle).
- tools: solo las herramientas que necesita; si no debe cambiar nada, solo lectura y búsqueda.
- model: propón uno y explícame por qué, aparte del archivo.
- El prompt de sistema: rol, a quién le sirve, reglas de voz o de calidad, disciplina de hechos y el formato de salida exacto.

Explícame en tres líneas cuándo Claude va a delegarle solo y cómo lo invoco yo.

Estas son las reglas de mi proyecto que no pueden fallar nunca, aunque el modelo las olvide:

[LISTA DE REGLAS, POR EJEMPLO: "ningún archivo de la carpeta contratos/ se edita", "todo archivo editado se formatea", "no se ejecutan comandos que borren carpetas"]

Para cada regla, dime si un hook es la herramienta correcta o si basta con una línea en CLAUDE.md o con un permiso, y por qué. Para las que sí son hooks, propón el evento (PreToolUse, PostToolUse, Stop u otro), el filtro de herramienta y el comando, en el formato de .claude/settings.json de Claude Code. Prefiere scripts cortos y legibles en .claude/hooks/ a comandos largos en una sola línea.

No modifiques nada todavía: muéstrame la configuración, explícame qué hace cada línea y cómo probar cada hook con un cambio inofensivo.

¿Qué es un plugin y cuándo lo necesito?

Un plugin es una carpeta con skills, subagentes, hooks o servidores MCP que Claude Code instala y carga como una sola unidad, normalmente desde un catálogo llamado marketplace, con el comando /plugin. Lo necesitas solo cuando quieres empaquetar varias piezas para tu equipo o para muchos proyectos; un skill o un hook sueltos funcionan sin plugin. Dos advertencias de la documentación: un plugin habilitado ocupa contexto en todas tus sesiones, aunque no lo uses, y lo que ejecuta, lo ejecuta como tú. Revísalo antes de instalarlo.

El siguiente módulo cierra la parte 3: MCP, la nube y agentes que trabajan mientras duermes, donde conectas Claude Code a tus herramientas y programas rutinas como las automatizaciones del módulo 8.