Claude Code — Reglas, Skills, Hooks y más para nuestro Claudio

¡Bienvenidos al hilo sobre Herramientas CLI y Agentes de IA! En este espacio vamos a hablar de cómo potenciar nuestro flujo de trabajo directamente desde la terminal, abordando conceptos clave como los archivos CLAUDE.md, las Skills, los Hooks, los Subagentes y otras utilidades que están revolucionando la forma en que interactuamos con nuestros proyectos.

Empezaremos por lo más fundamental, cómo darle memoria y contexto a tu agente, y desde ahí iremos escalando hacia capacidades cada vez más potentes.

---

CLAUDE.md — La memoria del proyecto

Claude Code tiene dos sistemas de memoria complementarios que se cargan al inicio de cada conversación. Ambos son tratados como contexto (no como configuración forzada): cuanto más específicas y concisas sean las instrucciones, más consistentemente las seguirá Claude.

Documentación oficial: https://code.claude.com/docs/en/memory

1. Archivos CLAUDE.md (instrucciones manuales)

Son archivos markdown que tú escribes para darle a Claude contexto persistente sobre tu proyecto. Se cargan automáticamente en la ventana de contexto al inicio de cada sesión.

Jerarquía y alcance

Claude Code busca y carga archivos CLAUDE.md de varias ubicaciones, con una jerarquía clara:

Las configuraciones de niveles superiores (Managed > User > Project) prevalecen sobre las inferiores.

Reglas por ruta con .claude/rules/

Para proyectos grandes, puedes organizar las instrucciones en archivos modulares dentro de .claude/rules/. Cada archivo cubre un tema, y puedes incluso acotar reglas a rutas específicas con frontmatter paths:, de modo que solo se cargan cuando Claude trabaja con archivos que coinciden con el patrón:

tu-proyecto/
├── .claude/
│   ├── CLAUDE.md
│   └── rules/
│       ├── testing.md          # Se carga siempre
│       ├── api-design.md       # Se carga siempre
│       └── frontend/
│           └── components.md   # Se carga siempre (o con paths: para acotar)

Importar archivos adicionales con @path

Puedes referenciar archivos externos desde tu CLAUDE.md para mantenerlo corto:

# Proyecto: Mi App
 
## Convenciones generales
- TypeScript estricto, sin `any`.
- Conventional Commits.
 
@docs/architecture.md
@docs/api-conventions.md

Tip: Los comentarios HTML (<!-- ... -->) se ocultan automáticamente a Claude cuando el CLAUDE.md se inyecta al inicio de sesión, así que puedes dejar notas para humanos sin gastar tokens.

Inicialización rápida con /init

El comando /init analiza tu codebase y genera un CLAUDE.md inicial como punto de partida.

2. Auto memory (memoria automática)

Además de los CLAUDE.md que tú escribes, Claude genera automáticamente un archivo MEMORY.md basado en tus correcciones y preferencias. Si corriges a Claude varias veces diciendo "en este proyecto usamos pnpm, no npm", guardará esa preferencia automáticamente. Se cargan las primeras 200 líneas o 25KB al inicio de cada sesión.

Gestiona la memoria con /memory (navegar, editar, eliminar) o pídele a Claude directamente que "recuerde" algo.

Buenas prácticas

• < 200 líneas por CLAUDE.md. Si crece, divide con @path imports o .claude/rules/.
• Sé específico y verificable: En lugar de "escribe buen código", di "no uses any en TypeScript, cada función pública con JSDoc".
• No repitas lo obvio: Solo incluye lo que Claude no pueda inferir del código.
• Compactación: Pon las reglas persistentes en CLAUDE.md (no solo en el chat). Añade una sección "Compact Instructions" para controlar qué se preserva al compactar.

---

¿Qué son las Skills?

En el ecosistema de agentes de IA por terminal, las Skills son extensiones basadas en prompts que amplían lo que la IA puede hacer. Al ejecutarse, la IA puede generar subagentes en paralelo, navegar y analizar archivos, y adaptarse al contexto de tu codebase.

Las skills de Claude Code siguen el estándar abierto "Agent Skills", extrapolable a Cursor, Codex CLI, Gemini CLI, etc.

Documentación oficial: https://code.claude.com/docs/en/skills

Estructura de una skill

Toda skill nace de un archivo SKILL.md con dos partes: un YAML frontmatter (entre ---) que configura name, description y opciones, y el contenido markdown con las instrucciones que la IA sigue al activarse.

Ejemplo de estructura básica:

---
name: explain-code
description: Explica el código usando diagramas visuales y analogías. Úsala cuando el usuario pregunte "¿cómo funciona esto?".
---
 
Cuando expliques código, incluye siempre:
 
1. **Una analogía:** Compara el código con algo de la vida cotidiana.
2. **Un diagrama:** Usa arte ASCII para mostrar el flujo o estructura.
3. **Paso a paso:** Explica qué ocurre de forma conversacional.
4. **Un "gotcha":** Señala errores comunes o malentendidos típicos.

Estructura de carpetas de una skill

Una skill puede ser solo un archivo, o un directorio completo con recursos adicionales:

.claude/skills/
└── mi-skill/
    ├── SKILL.md              # (obligatorio) Instrucciones principales
    ├── scripts/              # Scripts ejecutables para tareas deterministas
    │   └── validate.py
    ├── references/           # Documentación de referencia (se carga bajo demanda)
    │   └── api-spec.md
    └── assets/               # Plantillas, fuentes, iconos...
        └── template.html

La clave aquí es el concepto de Progressive Disclosure (revelación progresiva): al inicio, el agente solo carga el name y la description de cada skill en el prompt del sistema. Son metadatos ligeros. Solo cuando una skill se activa, el agente lee el SKILL.md completo y, si las instrucciones hacen referencia a otros archivos (como references/api-spec.md), los lee también bajo demanda. Esto mantiene la ventana de contexto limpia.

¿Dónde se guardan las skills?

Opciones avanzadas del frontmatter

Más allá de name y description, hay opciones útiles:

• allowed-tools: Restringe las herramientas que la IA puede usar al ejecutar la skill (ej: [Read, Grep, Glob] para una skill de solo lectura).
• disable-model-invocation: true: Solo tú puedes invocar esta skill (la IA no la activará sola). Útil para skills con efectos secundarios como despliegues.
• user-invocable: false: Solo la IA puede invocarla. Ideal para convenciones y guías que el agente debe aplicar automáticamente.
• context: fork: Ejecuta la skill en un subagente aislado para no contaminar el contexto de tu conversación principal.
• argument-hint: Muestra una pista del argumento esperado, ej: "[nombre-del-archivo]".

---

¿Qué son los Hooks?

Si las Skills son "el qué", los Hooks son "el cuándo". Son disparadores que ejecutan comandos, prompts o subagentes en puntos específicos del ciclo de vida del agente. A diferencia de las instrucciones en CLAUDE.md (que son sugerencias), los hooks proporcionan control determinista: una acción garantizada que se ejecuta siempre.

Documentación oficial: https://code.claude.com/docs/en/hooks

El ciclo de vida de un hook

Ejecución del agente → Evento específico se dispara → Matcher lo evalúa → Hook se ejecuta

Los hooks se disparan en momentos concretos de la sesión. Los eventos principales son:

Hay más eventos (como PermissionRequest, Elicitation, ConfigChange...), pero estos cubren los casos más comunes.

¿Dónde se configuran?

Los hooks se definen en archivos settings.json, que pueden estar en tres lugares:

• ~/.claude/settings.json — Usuario: Se aplican a todos tus proyectos.
• .claude/settings.json — Proyecto: Específicos del repo, se commitean para compartir con el equipo.
• .claude/settings.local.json — Proyecto local: Solo para ti, no se commitean.

Claude Code busca hooks en los tres archivos y dispara todos los que coincidan.

Tipos de handlers

Cuando un hook se dispara, ¿qué ejecuta? Hay cuatro tipos:

1. command (Comando shell): Ejecuta un script que recibe JSON por stdin y comunica resultados mediante exit codes y stdout. Es el tipo más directo.

2. http: Envía el JSON del evento como POST a una URL. El endpoint responde con el mismo formato JSON que los hooks de comando.

3. prompt: Envía un prompt a un modelo de Claude para evaluación de una sola vez (sí/no). Ideal para validaciones semánticas.

4. agent: Lanza un subagente con acceso a herramientas como Read, Grep y Glob para verificaciones más profundas antes de tomar una decisión.

Ejemplo práctico: Bloquear comandos destructivos

Un hook PreToolUse que impide que Claude ejecute rm -rf o DROP TABLE:

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "echo \"$CLAUDE_TOOL_INPUT\" | grep -qE 'rm -rf|DROP TABLE' && exit 2 || exit 0"
          }
        ]
      }
    ]
  }
}

La magia está en los exit codes:

• Exit 0: Todo OK, la acción procede. Claude Code parsea stdout buscando JSON.
• Exit 2: Error bloqueante. La acción se cancela y stderr se envía a Claude como mensaje de error.
• Cualquier otro código: Error no bloqueante (se registra pero no detiene la ejecución).

Modificar inputs (desde v2.0.10)

Los hooks PreToolUse también pueden modificar los inputs antes de que se ejecuten, no solo bloquearlos. El script intercepta, modifica el JSON, y la ejecución continúa con los parámetros corregidos (normalizar rutas, inyectar variables, forzar dry-run, etc.).

Condicionales con if: Filtrado granular

El matcher filtra solo por nombre de herramienta. Pero ¿y si quieres que un hook se ejecute solo para git push, no para cualquier comando Bash? Ahí entra el campo if, que se establece a nivel del handler y usa la sintaxis de reglas de permisos para matchear herramienta y argumentos:

• "Bash(git *)" → Solo comandos git.
• "Edit(*.ts)" → Solo archivos TypeScript.
• "Write(src/api/*)" → Solo escrituras en src/api/.

{
  "hooks": {
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": "npm run lint",
            "if": "Bash(git push*)"
          }
        ]
      }
    ]
  }
}

Sin el if, el lint se ejecutaría con cada ls o pwd. Con él, solo se dispara en git push.

Para combinar condiciones distintas, usa handlers separados cada uno con su propio if dentro del mismo matcher group (ej: uno con "if": "Edit(*.ts)", otro con "if": "Write(.env*)", etc.).

Restricciones: El if solo funciona en PreToolUse, PostToolUse, PostToolUseFailure y PermissionRequest — añadirlo a otro evento impide que el hook se ejecute. No soporta pipe dentro del if; para eso usa handlers separados o alternación en el matcher.

---

Subagentes

Los subagentes son asistentes de IA especializados que operan dentro de su propia ventana de contexto. Cuando Claude encuentra una tarea que encaja con la descripción de un subagente, le delega el trabajo. El subagente trabaja de forma independiente y devuelve los resultados.

¿Por qué usar subagentes?

El principal beneficio es preservar el contexto. Si le pides a Claude que haga una investigación profunda de tu repositorio, esa exploración puede consumir gran parte de tu ventana de contexto. Con un subagente, ese trabajo se hace en una ventana aparte y solo los resultados vuelven a tu conversación principal.

Subagentes incorporados

Claude Code incluye subagentes de fábrica que usa automáticamente:

• Explore: Para exploración y lectura del repositorio. Ideal en modo plan.
• Plan: Para diseñar estrategias de implementación sin hacer cambios.
• General-purpose: Para tareas diversas delegadas.

Creando subagentes personalizados

Se definen como archivos markdown en .claude/agents/:

.claude/agents/
└── code-reviewer/
    └── AGENT.md

---
name: code-reviewer
description: Revisor de código experto. Úsalo proactivamente después de cambios de código.
tools: Read, Grep, Glob, Bash
model: sonnet
---
 
Eres un revisor de código senior. Cuando revises código:
 
- Busca vulnerabilidades de seguridad (SQL injection, XSS, etc.)
- Verifica que se siguen las convenciones del proyecto.
- Señala problemas de rendimiento.
- Sugiere mejoras concretas con ejemplos.

El campo tools restringe qué herramientas puede usar (en este caso, solo lectura y búsqueda). El campo model permite usar un modelo más barato (como Haiku) para tareas sencillas y así controlar costes.

Subagentes con memoria

Los subagentes pueden tener su propio archivo MEMORY.md que persiste entre sesiones. Puedes pedirle al subagente que consulte su memoria antes de empezar ("revisa tu memoria por patrones que hayas visto antes") y que la actualice al terminar ("guarda lo que has aprendido en tu memoria"). Con el tiempo, esto construye una base de conocimiento que hace al subagente cada vez más efectivo.

Foreground vs Background

Los subagentes pueden ejecutarse en primer plano (bloquean la conversación hasta que terminan) o en segundo plano (trabajan concurrentemente). Los de segundo plano son ideales para tareas que no necesitan interacción, como análisis de logs o ejecución de tests.

Documentación oficial de Subagentes: https://code.claude.com/docs/en/sub-agents

---

Slash Commands (Comandos con /)

Los slash commands son atajos que se ejecutan escribiendo /nombre en la terminal del agente. Históricamente existían como sistema separado (archivos .md en .claude/commands/), pero actualmente se han fusionado con las skills: ambos crean el mismo tipo de /comando. El formato de skills (.claude/skills/) es el recomendado porque soporta archivos complementarios, frontmatter avanzado y activación autónoma.

La diferencia clave: manual vs automático

• Slash commands: Requieren que tú los invoques manualmente con /nombre.
• Skills: Pueden ser invocadas tanto manualmente como automáticamente por Claude cuando detecta que son relevantes.

Comandos incorporados útiles

Claude Code trae más de 55 comandos incorporados. Algunos de los más útiles:

• /compact — Comprime el historial de la conversación. Esencial para sesiones largas.
• /clear — Limpia el contexto entre tareas no relacionadas.
• /diff — Visor interactivo de todos los cambios que Claude ha hecho.
• /plan — Entra en modo plan (también se puede alternar con Shift+Tab).
• /memory — Ver y editar la memoria persistente del proyecto.
• /context — Muestra una cuadrícula de cómo se está usando la ventana de contexto.
• /loop [intervalo] [tarea] — Ejecuta una tarea en bucle (ej: /loop 5m check if deploy is done).
• /batch — Aplica cambios en múltiples archivos en paralelo.

---

MCP (Model Context Protocol) — El adaptador universal

El Model Context Protocol es un protocolo abierto que conecta a los agentes de IA con herramientas y fuentes de datos externas. Piensa en MCP como un "USB-C" para la IA: una interfaz estándar para conectarse a GitHub, bases de datos, APIs, Slack, Google Drive y cualquier servicio que tenga un servidor MCP.

Cómo funciona en la práctica

# Instalar un servidor MCP
claude mcp add playwright npx @playwright/mcp@latest
 
# Usarlo como comando
/mcp__playwright__create-test [args]

Al conectar un servidor MCP, obtienes acceso a sus herramientas, recursos y prompts como slash commands dentro de tu sesión.

MCP vs Skills vs Hooks

---

Scripts personalizados — El pegamento del workflow

Las docs oficiales cubren CLAUDE.md, Skills, Hooks y Subagentes, pero hay una pieza que queda fuera: los scripts propios que conectan todo. Los hooks disparan acciones, pero esas acciones necesitan lógica real — y ahí es donde entran tus scripts.

Un buen ejemplo de referencia es steipete/agent-scripts de Peter Steinberger — un repo público con guardrails compartidos entre proyectos: committer, políticas git, gestión de docs, trash como reemplazo de rm, y más. Muchos de los patrones que se describen a continuación siguen el mismo enfoque.

A continuación, un ejemplo real de cómo un workflow completo puede orquestarse con scripts que los hooks ejecutan. No es una receta única; es un patrón que puedes adaptar.

Estructura de ejemplo que uso yo

~/.claude/workflow/
├── scripts/
│   ├── committer              # Único camino permitido para commits
│   ├── git-policy.ts          # Política de seguridad git
│   ├── fetch-docs.ts          # Descarga docs de URLs a markdown
│   ├── chunk-docs.ts          # Divide docs grandes en chunks
│   ├── trash.ts               # Mover a papelera (nunca rm)
│   └── kill-stale-claude.sh   # Limpia sesiones Claude viejas
├── global/
│   ├── CLAUDE.md              # Protocolo global
│   └── bin/git                # Git shim (intercepta todo git)
└── templates/
    └── CLAUDE.md              # Template para proyectos nuevos

Patrón 1: Commit seguro con committer + git-policy.ts

La idea: git add y git commit directos están bloqueados. El único camino para commitear es un script committer que:

• Solo hace staged de archivos listados explícitamente (nunca git add .)
• Bloquea si el path es "." o el mensaje está vacío
• Valida formato Conventional Commits
• Genera un token temporal que autoriza al git shim a ejecutar las operaciones

¿Y quién bloquea los comandos git directos? Un script git-policy.ts que el git shim ejecuta antes de cada operación:

Comando git entra
  └─> git-policy.ts clasifica:
      ├── safe (status, log, diff, branch) → pasa siempre
      ├── blocked (add, commit) → solo con token de committer
      ├── guarded (push, pull, merge) → requiere consentimiento explícito
      └── destructive (reset --hard, push --force) → requiere consentimiento explícito

Esto convierte a Claude en un agente que no puede saltarse tu política de commits, sin importar cómo formule el comando.

Patrón 2: Quality gates con markers

Un paso más allá: no solo controlar cómo se commitea, sino exigir que se hayan completado pasos de revisión previos. Cada paso deja un marker (un archivo temporal), y el siguiente paso lo requiere:

Si Claude intenta commitear sin haber pasado los tres pasos, el script lo bloquea. Los markers se limpian automáticamente con un hook PostToolUse tras cada commit exitoso.

Patrón 3: Supervivencia a la compactación

Cuando la ventana de contexto se llena y Claude compacta, se pierde estado. Dos scripts resuelven esto:

• pre-compact-handoff.sh — Antes de compactar: guarda working tree, archivos sin commit, commits recientes y plan activo en un archivo temporal.
• post-compact-pickup.sh — Después de compactar: lee ese archivo y lo inyecta al contexto, incluyendo recordatorios del workflow.

Enganchados a los hooks correspondientes, hacen que Claude "recuerde" lo esencial tras cada compactación.

Patrón 4: Pipeline de documentación

Para mantener docs de referencia actualizadas y optimizadas para LLMs:

• fetch-docs.ts — Descarga documentación desde URLs usando Chrome headless + Readability.js + Turndown. Soporta crawling con profundidad configurable y deduplica contenido repetido (navbars, footers).
• chunk-docs.ts — Divide documentos grandes en chunks de _40K tokens respetando límites naturales de página, y genera un archivo índice.
• trash.ts — Reemplaza rm en todo el workflow. Mueve a papelera (~/.Trash en macOS, ~/.local/share/Trash/files en Linux). Borrado permanente prohibido.

Patrón 5: Hooks de sesión

Dos hooks que acotan el inicio y fin de cada sesión:

• session-snapshot.sh (SessionStart) — Captura qué archivos ya estaban dirty al inicio para que el stop gate no los cuente como pendientes.
• stop-gate.sh (Stop) — Bloquea terminar la sesión si hay cambios source sin commitear. Ignora archivos que ya estaban dirty y archivos de config (.md, .json, .yaml).

El flujo completo

Sesión inicia
  └─> session-snapshot.sh (captura estado inicial)
 
Edición de archivos
  └─> PostToolUse: auto-lint / auto-typecheck
 
Quiero commitear
  └─> /code-review  → /simplify  → /verify  → committer
       └─> git-policy.ts valida el token
       └─> git add + git commit ejecutan
       └─> PostToolUse limpia markers
 
Compactación de contexto
  └─> pre-compact-handoff.sh → post-compact-pickup.sh
 
Fin de sesión
  └─> stop-gate.sh (bloquea si hay cambios sin commitear)

La clave es que ninguna de estas piezas funciona sola: los hooks disparan los scripts, los scripts aplican las políticas, el CLAUDE.md le dice a Claude que use committer en lugar de git commit, y las skills orquestan los quality gates. Es el stack completo en acción.

---

Cómo encaja todo

Cada pieza cubre un rol distinto: CLAUDE.md da contexto, Skills dan instrucciones especializadas, Hooks garantizan acciones, Scripts implementan la lógica, Subagentes aíslan trabajo pesado, MCP conecta servicios externos, y los slash commands dan control manual. Veámoslo en un flujo real:

Tú escribes: "Implementa la feature de autenticación con JWT"
 
1. Claude lee CLAUDE.md → sabe que usas Express + TypeScript + Prisma
2. Claude activa la skill "api-conventions" → sigue tus patrones de API
3. Claude delega exploración al subagente Explore → escanea el repo sin gastar tu contexto
4. Claude implementa el código
5. Hook PostToolUse → script de auto-lint formatea cada archivo
6. Hook PreToolUse → git-policy.ts bloquea si intenta git add/commit directo
7. Quality gates: /code-review → /simplify → /verify
8. committer "feat(auth): add JWT authentication" "src/auth.ts" "src/middleware.ts"
9. Claude termina → Hook Stop → stop-gate.sh verifica que no queda nada pendiente

---

¿Y ahora qué?

La idea de este hilo es que podamos construir entre todos en Mediavida una biblioteca compartida: skills que os funcionen, configuraciones de hooks que hayáis probado, normas para CLAUDE.md (tanto globales como específicas de stack), scripts, workflows... Todo lo que os haya ahorrado tiempo o dolores de cabeza.

Compartid lo que tengáis, preguntad lo que necesitéis, y vamos montando algo útil para todos.

---

Recursos y enlaces

• Documentación oficial de Claude Code: https://code.claude.com/docs/en/
• Skills: https://code.claude.com/docs/en/skills
• Hooks: https://code.claude.com/docs/en/hooks
• Subagentes: https://code.claude.com/docs/en/sub-agents
• Repositorio oficial de Skills de Anthropic: https://github.com/anthropics/skills
• Biblioteca de skills: https://skills.sh/
• Awesome Claude Code (lista curada de la comunidad): https://github.com/hesreallyhim/awesome-claude-code
• agent-scripts (scripts de guardrails compartidos por Peter Steinberger): https://github.com/steipete/agent-scripts
• Blog de ingeniería de Anthropic sobre Agent Skills: https://www.anthropic.com/engineering/equipping-agents-for-the-real-world-with-agent-skills
• Herramienta para adaptar web de docs para agentes de AI: https://llm.codes/