Skills, Subagentes y Hooks

Claude Code no se limita a responder prompts sueltos: expone piezas que se combinan para armar flujos de trabajo repetibles. Conviene leerlas en este orden: en este artículo, las que corren dentro de una sesión (Skills, subagentes y Hooks); en MCP, la conexión con herramientas externas; y en Plugins, el empaquetado de todo lo anterior para distribuirlo. Las tres piezas de hoy especializan a Claude, pero no de la misma manera.

Skill vs Subagente: la diferencia de fondo

Es la confusión más común, porque ambos especializan a Claude — pero no del mismo modo.

• Una skill especializa el método. Dice: “cuando aparezca este tipo de tarea, seguí esta receta, usá estos recursos, esta plantilla, esta validación.” Es conocimiento y proceso empaquetado.
• Un subagente especializa al ejecutor. Dice: “delegale este problema a un agente pensado específicamente para este trabajo.” Es un rol, con su propio contexto y, muchas veces, sus propias restricciones de herramientas.

Preguntas rápidas para decidir:

Y, en la práctica, casi siempre rinde más combinarlas: un subagente explora y detecta patrones → una skill convierte ese análisis en una salida con formato fijo (un PRD, un post, un changelog) → un hook valida el resultado antes de dar la tarea por cerrada.

Skills: un método que Claude sabe usar cuando toca

Los comandos slash personalizados —antes definidos en .claude/commands/— se fusionaron con las skills en versiones recientes: un archivo en .claude/commands/deploy.md y una skill en .claude/skills/deploy/SKILL.md generan el mismo /deploy y se comportan igual. Los definidos a la manera anterior siguen funcionando.

Una skill vive en .claude/skills/nombre/SKILL.md, con frontmatter YAML y el cuerpo en Markdown:

---
name: revisar-pr
description: >                    # Claude lee esto para decidir cuándo cargarla
  Revisa el diff de un PR contra las guías de estilo y seguridad del
  equipo, antes de pedir el review de una persona.
argument-hint: "[numero-de-pr]"   # hint en el autocompletado
disable-model-invocation: true    # tiene efectos colaterales (comenta en el PR): solo vos la disparás
allowed-tools: Read Bash(gh pr diff *)   # pre-aprobadas, sin prompt, mientras corre
model: sonnet
effort: medium
context: fork                     # corre en un subagente aislado
agent: Explore                    # a qué subagente delega si usás context: fork
paths: "src/**/*.ts"              # solo se activa cuando tocás estos archivos
---
Instrucciones en Markdown para el cuerpo de la skill.
$ARGUMENTS = todo lo que sigue a /nombre-de-skill
${CLAUDE_SKILL_DIR} = carpeta donde vive la skill

Dos campos generan confusión y vale la pena tenerlos claros:

• disable-model-invocation: true → solo vos podés dispararla (con /nombre); Claude nunca la va a usar por su cuenta. Pensala para acciones con efectos secundarios donde el timing importa: /deploy, /commit, /send-slack-message.
• user-invocable: false → solo Claude puede usarla; no aparece en tu menú /. Pensala para conocimiento de fondo que Claude debería aplicar solo, pero que no es una “acción” que vos dispararías a mano (ej.: convenciones de un sistema legacy).

Cuándo crear una skill: repetís la misma receta seguido, una parte de tu CLAUDE.md ya es un proceso de muchos pasos en vez de una regla, o querés empaquetar instrucciones + plantillas + scripts (auditar un workflow, generar un PRD, redactar posts con un tono fijo).

Dos ejemplos reales del ecosistema de skills de terceros:

• caveman — cambia el estilo de comunicación de Claude a uno ultra-comprimido (fragmentos en vez de prosa, sin artículos ni relleno) para reducir tokens de salida sin perder precisión técnica. Es una skill de proceso: no toca qué hace Claude, sino cómo lo cuenta.
• ui-ux-pro-max — empaqueta conocimiento de diseño (paletas de producto, pares tipográficos, guías de UX, presets de animación) como una base de datos consultable, para que Claude tome decisiones de UI/UX fundamentadas en vez de “inventar” un estilo genérico. Es una skill de conocimiento de dominio.

Documentación relacionada: referencia oficial de Skills.

Subagentes: a quién delegarle una tarea

Un subagente se define en Markdown con su propio frontmatter, y no recibe el system prompt completo de Claude Code — solo el contenido de su archivo más detalles básicos del entorno:

---
name: auditor-seguridad
description: >                    # CRÍTICO para la delegación automática
  Revisa cambios de código en busca de vulnerabilidades comunes:
  inyección, secrets, validación y permisos. Use proactively después
  de cualquier cambio en rutas de la API.
tools: Read, Grep, Glob, Bash(npm audit)   # allowlist de herramientas
model: opus                       # sonnet | opus | haiku | inherit
permissionMode: default
maxTurns: 15
memory: project                   # memoria persistente entre sesiones
background: false
isolation: worktree                # copia aislada del repo vía git worktree
---
System prompt del subagente en Markdown.

Claude Code trae subagentes integrados como Explore (búsqueda y análisis de código, modelo rápido, solo lectura) y Plan. Tiene sentido crear uno propio cuando la tarea es más “rol especializado” que “receta de formato”: un revisor de seguridad, un analista de performance, un investigador de incidentes.

Subagentes propios habituales en un equipo:

Documentación relacionada: referencia oficial de Subagentes.

Hooks: lo que debe pasar sí o sí

Un hook es un script (o endpoint HTTP, prompt de un modelo, o subagente) que se dispara automáticamente en un punto del ciclo de vida. La diferencia con CLAUDE.md es la clave: CLAUDE.md es una sugerencia que el modelo puede o no seguir; un hook es determinista.

Si CLAUDE.md es un cartel de “por favor, cerrá la puerta al salir”, un hook es el mecanismo que la cierra solo, siempre.

Los cuatro tipos de handler:

Eventos más usados en flujos profesionales:

Exit codes (para hooks command):

• Exit 0 → éxito. El stdout se parsea como JSON para campos de control; en UserPromptSubmit y SessionStart se agrega como contexto visible para Claude.
• Exit 2 → error bloqueante. El stderr se le manda a Claude como error, y bloquea la operación (en los eventos que lo soportan, como PreToolUse, Stop o UserPromptSubmit).
• Cualquier otro código → error no bloqueante. Ojo con este: el exit code 1 NO bloquea nada, es una fuente clásica de bugs. Si tu hook tiene que impedir una acción, usá exit 2.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [{ "type": "command", "command": ".claude/hooks/block-payments-writes.sh" }]
      }
    ],
    "PostToolUse": [
      {
        "matcher": "Edit|Write|MultiEdit",
        "hooks": [{ "type": "command", "command": "npx eslint --fix $(jq -r '.tool_input.file_path')" }]
      }
    ]
  }
}

Este es el subsistema que cambia con más frecuencia en Claude Code: la lista completa hoy supera los 25-30 eventos (incluye PreCompact, ConfigChange, FileChanged, TaskCreated, entre otros más específicos), y no todos bloquean vía exit 2. Antes de apoyarte en un hook nuevo para algo crítico, conviene confirmar el comportamiento exacto del evento en la documentación oficial.

Con Skills, subagentes y Hooks ya se puede hacer mucho dentro de una sesión. El paso siguiente es conectar Claude Code con herramientas que viven fuera de la máquina — de eso trata MCP.