Módulo 5: Skills y Hooks: automatizar tu workflow

Módulo 5: Skills y Hooks — automatizar tu workflow

Descripción

Ya dominas el workflow Explore → Plan → Code. Sabes cuándo explorar, cuándo planificar, y cuándo ejecutar. Gestionas el context window y decides cuándo empezar sesiones nuevas. Eso te pone por encima de la mayoría de usuarios de Claude Code. Ahora viene la pregunta lógica: ¿cómo haces que Claude Code se adapte a ti, y no al revés?

Este módulo enseña los dos mecanismos de extensión de Claude Code: Skills y Hooks. Los Skills son archivos markdown en .claude/skills/ que Claude lee y sigue como instrucciones — los invocas con slash commands (/nombre). Los Hooks son scripts que se ejecutan automáticamente en puntos específicos del ciclo de vida de Claude Code — antes de escribir un archivo, después de ejecutar un comando, al completar una tarea.

Juntos, Skills y Hooks convierten a Claude Code en una herramienta personalizada para tu proyecto. No estás limitado a lo que Claude Code sabe hacer por defecto — puedes enseñarle tus convenciones, automatizar tus validaciones, y construir un sistema de calidad que funciona sin que tengas que recordar ejecutarlo manualmente.

Dónde estamos en la guía

Módulo 01: Qué es Claude Code ✅
Módulo 02: Instalación y setup ✅
Módulo 03: CLAUDE.md y memoria ✅
Módulo 04: Workflow agentic ✅
Módulo 05: Skills y Hooks ← ESTÁS AQUÍ
Módulo 06: Subagents
Módulo 07: Integraciones (Git, SDK, Remote Control)
Módulo 08: Proyecto integrador

En los módulos anteriores configuraste Claude Code (Módulos 02-03) y aprendiste a trabajar con él (Módulo 04). Ahora pasamos de usar a extender. Este módulo te enseña a moldear Claude Code para que trabaje exactamente como necesitas.

El mental model: plugins para un agente de IA

Piensa en tu IDE. VS Code tiene extensiones. JetBrains tiene plugins. Estas herramientas te permiten agregar funcionalidad sin modificar el IDE mismo. Claude Code tiene un sistema análogo — pero para un agente de IA.

┌─────────────────────────────────────────────────────────────┐
│                    CLAUDE CODE                              │
│                                                             │
│  ┌─────────────┐     ┌─────────────┐     ┌──────────────┐  │
│  │   Skills     │     │   Hooks     │     │  Permissions │  │
│  │  (comandos   │     │  (eventos   │     │  (control    │  │
│  │  bajo demanda)│     │  automáticos)│     │  de acceso)  │  │
│  └─────────────┘     └─────────────┘     └──────────────┘  │
│         │                   │                    │          │
│         ▼                   ▼                    ▼          │
│  ┌──────────────────────────────────────────────────────┐   │
│  │           TU WORKFLOW PERSONALIZADO                  │   │
│  └──────────────────────────────────────────────────────┘   │
│                                                             │
└─────────────────────────────────────────────────────────────┘

Pero hay una diferencia clave: los plugins de un IDE extienden la UI. Los Skills y Hooks de Claude Code extienden el comportamiento del agente. No estás agregando un botón — estás definiendo cómo Claude piensa, actúa, y verifica su trabajo.

La analogía precisa

Concepto IDE	Concepto Claude Code	Qué hace
Extensión/plugin	Skill	Agrega capacidad nueva bajo demanda
Git hooks / watchers	Hook	Reacciona automáticamente a eventos
Permisos de workspace	Permission system	Controla qué puede y qué no puede hacer
Settings.json	CLAUDE.md + settings	Define el comportamiento base

La diferencia con CLAUDE.md

En el Módulo 03 configuraste CLAUDE.md — el archivo que Claude lee siempre al inicio de cada sesión. Skills y Hooks son diferentes:

Mecanismo	Cuándo se activa	Propósito
CLAUDE.md	Siempre, al inicio de sesión	Contexto base del proyecto
`.claude/rules/`	Siempre o por path (con frontmatter `paths`)	Reglas modulares por topic o scope
Skills	Tú con `/nombre` o Claude automáticamente basado en `description`	Tareas específicas y repetitivas
Hooks	Automáticamente, en 22+ eventos del ciclo de vida	Validaciones y automatizaciones

CLAUDE.md dice "qué es este proyecto". .claude/rules/ organiza reglas por topic. Skills dicen "cómo hago esta tarea". Hooks dicen "qué verifico automáticamente".

Objetivo del módulo

Al completar este módulo, serás capaz de:

✅ Crear Skills con el formato actual (SKILL.md + YAML frontmatter) e invocarlos con slash commands o dejar que Claude los invoque automáticamente vía description
✅ Configurar Hooks usando cualquiera de los 22+ eventos del ciclo de vida (PreToolUse, PostToolUse, UserPromptSubmit, SessionStart/End, PreCompact/PostCompact, etc.)
✅ Usar los 4 handler types de hooks: command, http, prompt, agent
✅ Automatizar validaciones con hooks (linting, testing, format, security checks)
✅ Entender el permission system y los 4 modos: default, accept edits, Auto mode (classifier, marzo 2026), bypass permissions
✅ Diseñar un pipeline de calidad automatizado para tu proyecto

Prerequisitos

Conocimiento requerido:

✅ Módulo 04 completado (workflow Explore → Plan → Code dominado)
✅ Módulo 03 completado (CLAUDE.md configurado en tu proyecto)
✅ Claude Code instalado y funcionando (Módulo 02)

Para la práctica:

✅ Un proyecto real con CLAUDE.md configurado
✅ Familiaridad con terminal y scripts básicos (bash)
✅ Node.js instalado (para hooks con scripts JS, si aplica)

Verificación rápida:

Antes de continuar, verifica que puedes responder estas preguntas:

¿Cuáles son los tres modos de Claude Code y cuándo usas cada uno?
¿Qué es CLAUDE.md y en qué se diferencia de un README?
¿Qué hace el parámetro /effort?

Respuestas

Explore (análisis read-only, para entender el codebase), Plan (diseño sin ejecución, para planificar antes de implementar), Agent/Code (ejecución completa, para implementar). El ciclo típico es Explore → Plan → Code.
CLAUDE.md es el archivo de memoria persistente de Claude Code. Define convenciones, stack, y reglas del proyecto. Claude lo lee al inicio de cada sesión. A diferencia de un README (para humanos), CLAUDE.md es para el agente.
El effort level controla la profundidad de razonamiento del modelo. Los modelos actuales — Opus 5, Sonnet 5 y Fable 5 — tienen 5 niveles (low, medium, high, xhigh, max) con high como default; xhigh es el recomendado para coding. Se configura con /effort, en /model con flechas ← →, o en settings.

Si no estás listo:

Revisa primero:

Módulo 03: CLAUDE.md y el sistema de memoria
Módulo 04: El workflow agentic

Roadmap del módulo

Este módulo tiene 5 cápsulas progresivas:

Cápsula 01 — Introducción al módulo (esta cápsula)

Contexto, mental model, y roadmap. Entiendes qué son Skills y Hooks y por qué importan.

Cápsula 02 — Crear skills (slash commands)

Cómo crear archivos de skill en .claude/skills/, nombrarlos, estructurarlos, e invocarlos con /nombre. Desde skills simples (crear un componente) hasta skills avanzados (que referencian otros archivos y templates). Best practices para skills de equipo vs personales.

Cápsula 03 — Hooks: lifecycle events

Los 5 eventos del ciclo de vida: PreToolUse, PostToolUse, Notification, Stop, SubagentStop. Cómo configurarlos en settings.json, crear scripts de hook, usar matchers para filtrar herramientas, y controlar el flujo con return codes.

Cápsula 04 — Automatizar validaciones

Aplicación práctica de hooks: construir un pipeline de calidad automatizado. Lint en cada escritura, tests después de implementar, validación de seguridad antes de commits. Cómo encadenar validaciones y evitar pitfalls (loops infinitos, hooks lentos).

Cápsula 05 — Permission system

El modelo de permisos de Claude Code: qué puede hacer por defecto, cómo se solicitan permisos, cómo configurar niveles de aprobación, y el flag --dangerously-skip-permissions. Seguridad y control en proyectos reales.

Mapa de progresión

Cápsula 01 (esta)     → Mental model y contexto
Cápsula 02            → Skills: tus slash commands personalizados
Cápsula 03            → Hooks: automatización basada en eventos
Cápsula 04            → Pipeline de validación automatizado
Cápsula 05            → Permisos: seguridad y control

Dificultad: ⭐ ──────────────────────────▶ ⭐⭐⭐

Las primeras dos cápsulas son fundamentales — entiendes y creas Skills. Las cápsulas 03-05 son intermediate/advanced — automatizas validaciones y controlas permisos.

Qué construirás en este módulo

A lo largo de las 5 cápsulas, crearás un sistema completo de extensión para tu proyecto:

Skills personalizados — al menos 2 slash commands invocables (ej. /create-component, /write-test)
Hooks configurados — al menos 2 hooks funcionales (ej. lint automático, tests post-implementación)
Pipeline de validación — un flujo automatizado que verifica calidad en cada acción de Claude
Configuración de permisos — settings ajustados a tu nivel de confianza y el tipo de proyecto

Al final del módulo, tu Claude Code no será genérico — será una herramienta personalizada para tu workflow.

Por qué esto importa

Sin Skills ni Hooks

Cada vez que quieres que Claude siga una convención específica, tienes que escribirla en el prompt:

> Crea un componente React. Usa TypeScript. Nombra el archivo 
  con PascalCase. Incluye un test en __tests__/. Usa CSS Modules. 
  Exporta como default. Agrega el barrel export en index.ts.

Eso son 6 instrucciones que tienes que recordar y escribir cada vez. Con un skill:

> /create-component UserProfile

Una línea. Las 6 instrucciones están en el archivo de skill, listas para ser usadas siempre.

Sin Hooks

Después de que Claude escribe un archivo, tienes que recordar pedir validación:

> Ejecuta eslint en el archivo que acabas de crear.
> Ahora ejecuta prettier.
> Ahora ejecuta los tests relacionados.

Con hooks configurados, todo eso pasa automáticamente después de cada escritura. No tienes que recordar nada.

El impacto compuesto

Skills y Hooks eliminan fricción repetitiva. En una sesión de 30 minutos, puedes ejecutar 10-15 tareas. Si cada tarea tiene 3-4 pasos manuales de validación, son 30-60 acciones que puedes automatizar. La ganancia no es solo de tiempo — es de consistencia. Los humanos olvidamos ejecutar el linter. Los hooks no.

Conexión con el proyecto integrador

En el Módulo 08, construirás una herramienta CLI completa con Claude Code. Para ese proyecto, usarás directamente lo que aprendes aquí:

Skills: Crearás al menos 2 skills personalizados para tu herramienta CLI (ej. /add-command para agregar un nuevo comando CLI, /write-test para crear tests con tu convención)
Hooks: Configurarás al menos 2 hooks (ej. lint automático después de cada escritura, tests después de implementar un comando nuevo)

Los Skills y Hooks no son solo un ejercicio — son parte de los criterios de evaluación del proyecto integrador.

Versiones y compatibilidad

Este módulo cubre:

Claude Code 2.0+
Opus 5 (1M token context window)
Sonnet 5 (1M token context window)
Haiku 4.5 (200K context window)

Features cubiertos:

✅ Skills en .claude/skills/ con slash commands
✅ Hooks: PreToolUse, PostToolUse, Notification, Stop, SubagentStop
✅ Hook matchers (Write, Execute, Read, etc.)
✅ Hook scripts (bash, Python, Node.js)
✅ Permission system (allowedTools, session permissions)
✅ Settings: .claude/settings.json y .claude/settings.local.json

Nota sobre cambios:

Claude Code se actualiza aproximadamente cada 2 días. Los conceptos de Skills, Hooks y Permissions son fundamentales a la arquitectura de Claude Code — la forma en que los invocas puede tener ajustes menores, pero la filosofía es estable. Siempre consulta la documentación oficial para verificar sintaxis exacta.

Un vistazo al módulo completo

Para que visualices cómo se integran Skills, Hooks y Permissions, aquí tienes un escenario real:

La sesión sin personalizar

> Crea un componente React para mostrar una lista de productos.

Claude crea el componente... pero usa CSS-in-JS en lugar de 
CSS Modules (tu convención). No incluye test. No pasa el linter.

> Oye, en este proyecto usamos CSS Modules, no styled-components.
> También necesito un test.
> Ejecuta eslint por favor.

3 correcciones manuales. Y esto pasa en CADA componente.

La sesión con Skills y Hooks

> /create-component ProductList

Claude lee el skill, sigue las convenciones, crea el componente 
con CSS Modules, genera el test, hace el barrel export.

[Hook PostToolUse] → ESLint ejecutado automáticamente → 0 errores
[Hook PostToolUse] → Prettier ejecutado → formato correcto
[Hook PostToolUse] → Tests ejecutados → 1/1 passing

0 correcciones manuales. Todo automático.

Esa es la diferencia. Y eso es lo que construirás en este módulo.

Conceptos clave que verás

Skills: tus slash commands

Un skill es un directorio en .claude/skills/ con un archivo SKILL.md que contiene YAML frontmatter + instrucciones. El nombre del directorio se convierte en el slash command:

.claude/skills/create-component/SKILL.md  →  /create-component
.claude/skills/write-test/SKILL.md        →  /write-test
.claude/skills/review-code/SKILL.md       →  /review-code

Un SKILL.md se ve así:

---
name: create-component
description: Crear un nuevo componente React siguiendo las convenciones del proyecto
---

Instrucciones que Claude sigue al invocar /create-component...

El campo description es crítico: Claude lo usa para invocar el skill automáticamente cuando detecta que es relevante a tu request. No hay API, no hay configuración compleja. El formato sigue el estándar abierto Agent Skills.

Hooks: automatización basada en eventos

Los hooks se configuran en .claude/settings.json y se ejecutan automáticamente cuando ocurren ciertos eventos:

Evento	Cuándo ocurre	Ejemplo de uso
PreToolUse	Antes de usar una herramienta	Bloquear escritura de secrets
PostToolUse	Después de usar una herramienta	Ejecutar linter automáticamente
Notification	Cuando Claude envía una notificación	Enviar alerta a Slack o terminal
Stop	Cuando el agente principal termina	Ejecutar suite de tests
SubagentStop	Cuando un subagent termina	Validar output del subagent

Los hooks son scripts (bash, Python, Node) que reciben información sobre la acción (qué archivo se modificó, qué comando se ejecutó) y pueden reaccionar.

Permission system: control granular

Claude Code tiene un sistema de permisos que controla qué puede hacer sin preguntar y qué requiere tu aprobación:

Read archivos      → ✅ Siempre permitido
Buscar en archivos → ✅ Siempre permitido
Escribir archivos  → ⚠️ Pide permiso (configurable)
Ejecutar comandos  → ⚠️ Pide permiso (configurable)

Puedes configurar allowedTools en settings para pre-aprobar ciertas acciones y reducir la fricción sin sacrificar seguridad.

La triada de control

┌──────────────────────────────────────────────────────┐
│                                                      │
│  PERMISSIONS          SKILLS           HOOKS         │
│  ┌────────────┐   ┌────────────┐   ┌────────────┐   │
│  │ Qué PUEDE  │   │ Qué SABE   │   │ Qué se     │   │
│  │ hacer      │   │ hacer      │   │ VALIDA     │   │
│  │            │   │            │   │ automática-│   │
│  │ (control)  │   │ (capacidad)│   │ mente      │   │
│  └────────────┘   └────────────┘   └────────────┘   │
│       │                │                │            │
│       └────────────────┼────────────────┘            │
│                        ▼                             │
│              WORKFLOW CONTROLADO                     │
│              Y PERSONALIZADO                         │
│                                                      │
└──────────────────────────────────────────────────────┘

Permissions definen los límites. Skills definen las capacidades. Hooks definen las verificaciones. Juntos, crean un agente que trabaja exactamente como necesitas.

Cómo se integra todo

Para que veas la imagen completa, aquí tienes cómo interactúan Skills, Hooks y Permissions en una sesión real:

Inicio de sesión

[Permission check] → Claude tiene permisos configurados en settings.json
[CLAUDE.md] → Claude lee el contexto del proyecto

Durante la sesión

Tú: /create-component ProductCard

[Skill] → Claude lee .claude/skills/create-component/SKILL.md
[Permission] → Write(src/**) está en allowedTools → procede sin preguntar
[Hook PreToolUse] → Security check: no hay secrets → procede
[Claude escribe el archivo]
[Hook PostToolUse] → Prettier formatea → ESLint valida → Tests relacionados pasan

Al terminar la tarea

[Hook Stop] → tsc --noEmit: ✅ | npm test: 14/14 passing
Claude: "Componente ProductCard creado con tests. Todo limpio."

Este flujo es completamente automático. Tú solo escribiste /create-component ProductCard. Todo lo demás — permisos, skill, hooks, validación — ocurrió sin intervención.

Resumen

Este módulo es donde Claude Code deja de ser una herramienta genérica y se convierte en tu herramienta.

Lo que aprendiste en esta cápsula:

Skills y Hooks son el sistema de extensión de Claude Code
Skills = slash commands bajo demanda, Hooks = automatizaciones basadas en eventos
CLAUDE.md define el contexto base; Skills definen tareas; Hooks definen automatizaciones
Skills eliminan la fricción de repetir instrucciones; Hooks eliminan la fricción de validar manualmente
En el proyecto integrador (Módulo 08) crearás 2+ skills y 2+ hooks reales

Siguiente cápsula: 02 - Crear skills (slash commands) — cómo crear, nombrar, estructurar e invocar tus propios comandos personalizados.

Recursos adicionales

Documentación oficial

Hooks — Lifecycle events y configuración de hooks
Plugins Reference — Skills, agents, hooks, MCP bundled
Settings — Configuración de scopes (global, project, local)

Best practices

Claude Code Best Practices — Workflows y context management
Memory — Cómo CLAUDE.md y Skills interactúan

Complementarios

CLI Reference — Todos los comandos y slash commands
Interactive Mode — Permisos y task management

← AnteriorCuándo Empezar una Nueva Sesión vs Continuar la Actual Siguiente →Crear Skills: extender Claude Code con instrucciones reutilizables