Skip to main content

​
Capítulo 6: Skills, hooks y gestión de contexto

El AGENTS.md es la base. Skills, hooks y gestión de contexto son las optimizaciones que hacen la diferencia entre “funciona” y “funciona consistentemente”.

​
Más allá del AGENTS.md

Los capítulos anteriores cubrieron los fundamentos: la cadena de artefactos (capítulo 3), el AGENTS.md como cerebro del proyecto (capítulo 4), y la guía de diseño evolutiva (capítulo 5). Con eso, un proyecto funciona. Pero “funciona” y “funciona bien a lo largo de 50 sesiones” son cosas distintas. Conforme el proyecto crece, aparecen tres problemas que el AGENTS.md solo no resuelve:
  1. El AGENTS.md se infla. Cada regla nueva, cada gotcha, cada convención se agrega al archivo. A las 200 líneas, la AI empieza a ignorar instrucciones del final. A las 400, hay reglas que se contradicen entre sí.
  2. Hay procesos que la AI debe seguir siempre, sin excepción. “Ejecutar Prettier después de cada edición” no es una sugerencia — es una obligación determinista. Pero el AGENTS.md es advisory: la AI lo sigue la mayoría del tiempo, no siempre.
  3. Las sesiones largas degradan la calidad. La AI tiene un contexto finito. Conforme la conversación crece, las instrucciones del inicio pierden peso frente a los mensajes recientes. Sin gestión activa, la sesión 1 produce excelentes resultados y la sesión 15 produce inconsistencias.
Este capítulo cubre las tres herramientas que resuelven estos problemas: skills para el primero, hooks para el segundo, y técnicas de gestión de contexto para el tercero.

​
Skills: conocimiento on-demand

​
Qué son

Un skill es un archivo markdown con conocimiento especializado que la AI carga solo cuando es relevante para la tarea actual. A diferencia del AGENTS.md (que se lee en cada sesión), los skills se activan bajo demanda — no ocupan contexto cuando no se necesitan.

​
Cuándo crear un skill

La regla de decisión es simple:
  • ¿Este conocimiento aplica a TODAS las tareas? → va en el AGENTS.md
  • ¿Este conocimiento aplica solo a ciertos tipos de tarea? → va en un skill
Ejemplos concretos:
Conocimiento¿Dónde?¿Por qué?
”Nunca hardcodear colores”AGENTS.mdAplica siempre, en toda tarea
Convenciones de i18n con next-intl v4SkillSolo cuando se trabaja en textos/traducciones
Clean Architecture: 3 capas, reglas de dependenciaSkillSolo cuando se trabaja en backend
Glosario del dominio de negocio (compliance, SAGRILAFT)SkillSolo cuando se implementan reglas de negocio
Patrones de testing E2E con helpers y mocksSkillSolo cuando se escriben tests
Patrones UX del proyectoSkillSolo cuando se trabaja en UI

​
Estructura de un skill

.claude/skills/{nombre}/SKILL.md
El archivo tiene frontmatter YAML + contenido markdown: 
---
name: i18n-patterns
description: "Convenciones de internacionalización con next-intl v4.
Activar cuando se trabaje con textos de UI, traducciones, o archivos
de mensajes."
---

# Convenciones i18n

## Estructura de archivos
- Mensajes en apps/web/messages/{locale}.json
- Namespaces por feature: home, auth, common, sidebar...

## Uso en componentes
- Client: useTranslations('namespace')
- Server: getTranslations('namespace')

## Reglas
- NUNCA hardcodear strings de UI
- Variables con ICU syntax: "daysAgo": "Hace {days} días"
- Acentos correctos en español
...
La descripción del frontmatter es clave. La AI usa esa descripción para decidir si cargar el skill. Una descripción vaga (“convenciones de código”) hace que el skill se cargue en momentos innecesarios. Una descripción precisa (“convenciones de next-intl v4, activar cuando se trabaje con traducciones”) hace que se cargue exactamente cuando se necesita.

​
Skills recomendados por tipo de proyecto

Para un proyecto web fullstack típico:
SkillContenidoSe activa cuando…
clean-architectureCapas, puertos, reglas de dependencia, wiring DISe trabaja en backend
testing-patternsEstructura E2E, helpers, mocks, patrón de testSe escriben tests
i18n-patternsConvenciones de la librería i18nSe trabaja con textos de UI
domain-{negocio}Glosario, reglas de negocio, entidades del dominioSe implementan features de negocio
ux-patternsProtocolo UX del proyectoSe trabaja en componentes de UI
No todos los proyectos necesitan todos estos skills. Crear un skill solo cuando el conocimiento es lo suficientemente extenso como para inflar el AGENTS.md (más de 10-15 líneas de reglas sobre un tema específico).

​
El principio agnóstico

Los skills son una feature de Claude Code, pero el concepto aplica a cualquier herramienta. En Cursor, el equivalente es .cursorrules con archivos adicionales referenciados. En Antigravity, es el contexto del proyecto con documentos adjuntos. El principio es el mismo: separar conocimiento general (siempre presente) de conocimiento especializado (disponible cuando se necesita). Para herramientas que no soportan carga progresiva, la alternativa es mantener los documentos de conocimiento especializado como archivos .md en el repo e instruir a la AI a consultarlos cuando trabaje en ciertos tipos de tarea: 
# En el AGENTS.md
## Documentación especializada
- Antes de trabajar en backend, leer `docs/CLEAN_ARCHITECTURE.md`
- Antes de trabajar en tests, leer `docs/TESTING_PATTERNS.md`
- Antes de trabajar en UI, leer `docs/UX_PATTERNS_PROTOCOL.md`
No es tan elegante como la carga automática de skills, pero logra el mismo resultado.

​
Hooks: automatización determinista

​
El problema que resuelven

El AGENTS.md es advisory — la AI lo sigue la mayor parte del tiempo, pero no siempre. Hay un porcentaje de sesiones donde la AI ignora una instrucción, especialmente cuando el contexto se ha acumulado y las instrucciones del AGENTS.md compiten con los mensajes recientes. Para reglas que deben cumplirse siempre, sin excepción, eso no es aceptable. “Ejecutar el formateador después de cada edición” no puede fallar el 5% de las veces — genera inconsistencias que se acumulan. Los hooks resuelven esto: son scripts que se ejecutan automáticamente cuando ocurre un evento específico. No dependen de que la AI “decida” ejecutarlos — se ejecutan siempre, de forma determinista.

​
Tipos de hooks

HookCuándo se ejecutaUso típico
PreToolUseAntes de que la AI use una herramientaBloquear acciones peligrosas, validar permisos
PostToolUseDespués de que la AI usa una herramientaFormatear código, ejecutar linter
StopCuando la AI termina de responderVerificar que los tests pasan, validar el resultado
UserPromptSubmitCuando el usuario envía un mensajePreprocesar input, inyectar contexto

​
El hook más útil: PostToolUse para formateo

Este es el hook que más impacto tiene con menos esfuerzo. Configura el formateador (Prettier, ESLint, etc.) para que se ejecute automáticamente después de cada edición de archivo: 
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write $FILE_PATH"
          }
        ]
      }
    ]
  }
}
Con esto, cada archivo que la AI edita o crea se formatea automáticamente. No importa si la AI “olvidó” respetar las convenciones de formato — el hook lo corrige siempre.

​
Hook de Stop para verificación

Un hook de Stop puede ejecutar verificaciones al final de cada turno de la AI: 
{
  "hooks": {
    "Stop": [
      {
        "type": "command",
        "command": "npx tsc --noEmit --pretty 2>&1 | head -20"
      }
    ]
  }
}
Si hay errores de tipos después de que la AI terminó, el hook los muestra inmediatamente — antes de que el humano tenga que recordar ejecutar typecheck manualmente.

​
Cuándo usar hook vs. regla en AGENTS.md

NecesidadHookAGENTS.md
Formateo de código✓ (determinista)
Linting automático✓ (determinista)
Ejecutar typecheck✓ (Stop hook)
No hardcodear colores✓ (guía, no automatizable)
Seguir clean architecture✓ (conceptual, no automatizable)
No modificar ciertos archivos✓ (PreToolUse bloqueante) o✓ (instrucción en contexto)
La regla: Si se puede automatizar con un script, es un hook. Si requiere juicio de la AI, es una instrucción en el AGENTS.md.

​
El principio agnóstico

Los hooks son específicos de Claude Code. En otras herramientas, el equivalente varía: Cursor tiene scripts de pre/post-save, algunas herramientas tienen extensiones o plugins. El principio subyacente es universal: lo que debe pasar siempre, debe ser automático — no depender de la buena voluntad de la AI. Para herramientas sin hooks nativos, la alternativa es incluir los comandos de verificación en el Protocolo de Cierre de Sesión como pasos que el humano ejecuta manualmente. Es menos elegante, pero cumple la función.

​
Gestión de contexto: la ventana finita

​
El problema

Cada AI coding agent tiene un contexto finito — una cantidad máxima de texto que puede “tener en mente” al mismo tiempo. Cuando la conversación crece (más mensajes, más archivos leídos, más código generado), las instrucciones del inicio — incluyendo el AGENTS.md — pierden peso relativo. Esto explica un patrón que todo usuario de AI coding agents ha experimentado: la primera hora de una sesión produce excelentes resultados, y la tercera hora produce inconsistencias. No es que la AI se “canse” — es que el contexto se saturó y las instrucciones tempranas quedan enterradas bajo capas de conversación.

​
Técnica 1: Sesiones limpias por tarea

La técnica más simple y efectiva: cada tarea significativa se hace en una sesión nueva. 
Sesión 1: Planificar + escribir spec → produce SPEC.md
    ↓ (cerrar sesión)
Sesión 2: Implementar backend → lee SPEC.md, implementa
    ↓ (cerrar sesión)
Sesión 3: Implementar frontend → lee SPEC.md + SESSION_LOG, implementa
La sesión 2 arranca con contexto limpio, enfocado enteramente en implementación. No arrastra los intercambios de planificación de la sesión 1. Tiene toda la ventana de contexto disponible para el AGENTS.md + la spec + el código. Cuándo aplicar: Siempre que cambies de tipo de tarea (planificar → implementar, backend → frontend, implementar → debuggear). Si vas a seguir haciendo lo mismo, mantener la sesión está bien.

​
Técnica 2: Compactar contexto (/compact)

Cuando la sesión se extiende y no quieres cerrarla, la compactación resume la conversación previa manteniendo lo esencial. El punto óptimo es compactar al alcanzar el 50% del contexto disponible — antes de que la degradación se note. El truco está en decirle a la AI qué preservar: 
/compact preserva: la lista de archivos modificados, el estado actual del feature,
y los errores que ya corregimos
Sin esa instrucción, la compactación puede descartar contexto que necesitas. Con ella, la AI sabe qué es prioritario retener. Cuándo aplicar: Sesiones largas donde has estado iterando sobre un feature y no quieres perder el hilo.

​
Técnica 3: Limpiar contexto (/clear)

Cuando necesitas un reset total dentro de la misma sesión — por ejemplo, terminaste un feature y vas a empezar otro — limpiar el contexto es más efectivo que compactar: 
/clear
El AGENTS.md se recarga. Los skills relevantes se recargan. Pero la conversación anterior desaparece. Es como abrir una sesión nueva sin cerrar la ventana. Cuándo aplicar: Al cambiar de tarea dentro de una sesión. Terminaste el backend de un feature y vas a empezar el frontend del mismo: /clear para que el contexto de la implementación backend no interfiera con las decisiones de frontend.

​
Técnica 4: Plan mode (revisión antes de ejecución)

Antes de que la AI ejecute una tarea compleja, activar el modo de planificación le obliga a presentar un plan que puedes revisar y editar antes de que escriba código. El flujo: 
1. Activar plan mode (Shift+Tab ×2 en Claude Code, o instrucción explícita)
2. La AI presenta un plan con pasos numerados
3. Revisar el plan — ¿los pasos son correctos? ¿falta algo? ¿sobra algo?
4. Editar el plan si es necesario (Ctrl+G abre en editor)
5. Aprobar → la AI ejecuta paso a paso
Cuándo aplicar: Features complejos (3+ archivos), cambios que afectan arquitectura, y cualquier tarea donde el costo de un error es alto. Para tareas simples (fix de un bug, ajuste cosmético), el plan mode es overhead innecesario. El principio agnóstico: No todas las herramientas tienen un “plan mode” formal. Pero el principio — pedirle a la AI que planifique antes de ejecutar — funciona en cualquier herramienta con un prompt: 
Antes de implementar, dame un plan con:
1. Qué archivos vas a modificar
2. En qué orden
3. Qué resultado esperas de cada paso

NO implementes nada hasta que yo apruebe el plan.

​
Técnica 5: Rewind (deshacer con contexto)

Cuando la AI tomó un camino incorrecto y quieres volver al estado anterior — no solo del código, sino de la conversación: 
Esc → detiene la acción actual (el contexto se preserva, puedes redirigir)
Esc + Esc → abre el menú de rewind para restaurar un punto anterior
Esto es más poderoso que un git checkout porque restaura tanto el código como el estado de la conversación. La AI “olvida” el intento fallido y puede intentar de nuevo con dirección diferente. Cuándo aplicar: Cuando la AI empezó a modificar archivos incorrectos, cuando un enfoque de implementación no funcionó, o cuando quieres probar una alternativa sin arrastrar el contexto del intento anterior.

​
Las tres capas de optimización

Estas tres herramientas forman capas sobre el AGENTS.md: 
Capa 3: Gestión de contexto (sesiones limpias, /compact, /clear, plan mode)
         → Cuándo y cómo la AI trabaja

Capa 2: Hooks (PostToolUse, Stop, PreToolUse)
         → Qué pasa automáticamente, siempre, sin excepción

Capa 1: Skills (conocimiento on-demand)
         → Qué sabe la AI cuando trabaja en un área específica

Base:    AGENTS.md (reglas universales del proyecto)
         → Qué sabe la AI siempre
No es necesario implementar las tres capas desde el día uno. La progresión natural es:
  1. Semana 1: AGENTS.md bien escrito (~150 líneas). Suficiente para empezar.
  2. Semana 2-3: Primer skill (el conocimiento que más inflaba el AGENTS.md). Sesiones limpias por tarea.
  3. Semana 4+: Hook de PostToolUse para formateo. /compact cuando las sesiones se alargan. Plan mode para features complejos.
  4. Mes 2+: Más skills conforme el proyecto crece. Hook de Stop para verificación. Rewind cuando hay que explorar alternativas.

​
Errores comunes

​
”Meto todo en el AGENTS.md y funciona”

Funciona al inicio. Deja de funcionar cuando el archivo pasa de 200 líneas. La AI tiene un límite práctico de instrucciones que puede seguir consistentemente — sobrepasar ese límite no produce errores explícitos, sino degradación silenciosa. La AI simplemente empieza a ignorar reglas, especialmente las del final del archivo.

​
”Configuro 10 skills desde el día uno”

Skills vacíos o con contenido genérico son peores que no tener skills — ocupan el presupuesto de carga sin aportar valor. Crear un skill solo cuando hay contenido real y probado que mover desde el AGENTS.md o desde la experiencia de implementación.

​
”Los hooks resuelven todo”

Los hooks resuelven lo automatizable. No resuelven “seguir clean architecture” ni “mantener consistencia de UX” — esas son decisiones que requieren juicio y van en el AGENTS.md o en skills. Usar hooks para lo que se puede automatizar y dejar el resto como instrucciones.

​
”No necesito gestionar el contexto, mis sesiones son cortas”

Si todas tus sesiones son menores a 30 minutos, probablemente no necesitas /compact ni /clear. Pero si alguna vez te encuentras pensando “la AI estaba funcionando bien al inicio y ahora está produciendo cosas raras”, la respuesta casi siempre es saturación de contexto. Compactar o limpiar resuelve el problema inmediatamente.

​
Resumen accionable

  1. Empieza con el AGENTS.md. No agregues skills ni hooks hasta que el AGENTS.md funcione bien por sí solo.
  2. Crea el primer skill cuando el AGENTS.md pase de 150 líneas. Mueve el bloque de conocimiento más extenso a un skill — típicamente arquitectura backend o patrones de testing.
  3. El primer hook debe ser PostToolUse para formateo. Es el de mayor impacto con menor esfuerzo. Elimina una categoría entera de inconsistencias.
  4. Usa sesiones limpias como regla, no como excepción. Una tarea = una sesión. Es la técnica de gestión de contexto más simple y más efectiva.
  5. Plan mode para lo complejo, ejecución directa para lo simple. No todo necesita un plan. Un fix de CSS no necesita plan mode. Un módulo nuevo con 5 archivos sí.
  6. Adapta a tu herramienta. Skills, hooks, /compact, plan mode son features específicas. Los principios detrás de ellos (conocimiento on-demand, automatización determinista, gestión de contexto finito, planificación antes de ejecución) son universales.