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.md	Aplica siempre, en toda tarea
Convenciones de i18n con next-intl v4	Skill	Solo cuando se trabaja en textos/traducciones
Clean Architecture: 3 capas, reglas de dependencia	Skill	Solo cuando se trabaja en backend
Glosario del dominio de negocio (compliance, SAGRILAFT)	Skill	Solo cuando se implementan reglas de negocio
Patrones de testing E2E con helpers y mocks	Skill	Solo cuando se escriben tests
Patrones UX del proyecto	Skill	Solo cuando se trabaja en UI

Estructura de un skill

.claude/skills/{nombre}/SKILL.md

Esa es la ruta que lee Claude Code. El paquete las copia a .agents/skills/, que no es de ninguna herramienta, y deja .claude/skills como enlace a esa carpeta.

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.

Del protocolo al skill

Los cuatro protocolos de la Parte III nacieron como documentos: un .md en docs/ que la AI leía cuando alguien se acordaba de pedírselo. Funcionaba, con una fuga conocida — el protocolo se aplicaba cuando el humano lo recordaba, no cuando la tarea lo requería.

Convertirlos en skills cierra esa fuga. El mismo contenido, con frontmatter que declara cuándo activarse, deja de depender de la memoria de nadie:

Como documento	Como skill
El humano recuerda cargarlo	La AI lo carga al detectar la tarea
Se lee entero o no se lee	Se carga solo cuando aplica
Explica el procedimiento	Ejecuta el procedimiento
Se desactualiza en silencio	Se rompe visiblemente cuando ya no aplica

La diferencia práctica es grande. Un protocolo de cierre en docs/ se cumple la mitad de las veces; el mismo protocolo como skill se cumple cuando la sesión termina, porque eso es lo que dice su descripción.

Esto no reemplaza al capítulo. El capítulo explica por qué el protocolo es así y qué criterio hay detrás de cada regla — eso lo lee un humano una vez. El skill es el procedimiento destilado que la AI ejecuta muchas veces. Se necesitan los dos: sin el capítulo, nadie sabe qué adaptar; sin el skill, nadie lo aplica consistentemente.

El paquete de inicio

Falcux AI-First incluye once skills listas para instalar. Cinco son protocolos: los cuatro de la Parte III en formato ejecutable y protocolo-arranque, que corre antes que todos y produce la spec que protocolo-features da por hecha; las otras seis nacieron resolviendo problemas concretos en proyectos reales y resultaron transferibles. Qué hace cada una y cuándo se activa está en Las 11 skills; instalarlas es un comando, npx @falcux/ai-first@latest init, que se explica en el Inicio rápido.

No instales las once el primer día. Por eso init, si no le dices otra cosa, instala sólo las cinco que no dependen de una interfaz —protocolo-features, protocolo-cambios, protocolo-cierre, test-fix y version-bump—; con la entrevista, suma las que el perfil del producto pida. El resto entra cuando el proyecto lo pide: protocolo-ux, el que más errores evita en un producto con interfaz, junto con information-architecture en cuanto haya más de un módulo; ux-writer e i18n antes de que el copy acumule deriva, porque retrofitearlos es caro; ux-audit cuando haya volumen que auditar. protocolo-arranque es la excepción: corre una vez, al principio, si el proyecto todavía no tiene PRD.

Las 11 skillsQué hace cada una, cuándo se activa y cuáles instala init por defecto.

Los dos tipos de skill

El paquete de inicio ilustra una distinción útil al decidir qué convertir en skill:

Skills de procedimiento — describen cómo se hace algo, paso a paso, con un orden que importa. protocolo-cierre y version-bump son de este tipo: tienen pasos numerados, gates de confirmación y un reporte de salida. Son los que más se benefician del formato, porque un procedimiento leído a medias produce resultados peores que ninguno.

Skills de criterio — describen cómo decidir algo. ux-writer y protocolo-ux son de este tipo: no tienen pasos, tienen reglas y una tabla de decisión. Su valor está en resolver por escrito las ambigüedades que de otro modo se resuelven distinto cada vez.

Un skill que no es ninguno de los dos — un volcado de información sin procedimiento ni criterio — probablemente sea documentación de referencia, y le sirve mejor a tu proyecto como un .md en docs/.

Skills que solo existen en tu proyecto

El paquete de inicio cubre lo transferible. Todo proyecto necesita además skills que nadie más puede escribir por él: el dominio de negocio, la arquitectura concreta, las integraciones externas, las reglas regulatorias.

El proyecto del que salió este paquete tiene 22 skills. Diez de las de aquí salieron de él —protocolo-arranque nació aparte, de lo que se hacía fuera del paquete—; el resto —motor de scoring, máquina de estados, aislamiento multi-tenant, marco regulatorio, integraciones con proveedores— no le sirve a nadie más, y son justamente las que más valor aportan ahí.

La proporción sana es esa: menos de la mitad heredado, el resto propio. Si todos tus skills son genéricos, la AI todavía no sabe nada específico de tu proyecto.

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/protocolo-ux.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

Hook	Cuándo se ejecuta	Uso típico
PreToolUse	Antes de que la AI use una herramienta	Bloquear acciones peligrosas, validar permisos
PostToolUse	Después de que la AI usa una herramienta	Formatear código, ejecutar linter
Stop	Cuando la AI termina de responder	Verificar que los tests pasan, validar el resultado
UserPromptSubmit	Cuando el usuario envía un mensaje	Preprocesar 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

Necesidad	Hook	AGENTS.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 del agente no son un estándar. A diferencia de las skills, que varias herramientas leen desde la misma carpeta, cada herramienta que tiene hooks los configura en su propio formato y con sus propios nombres de evento, y algunas sólo admiten plugins en vez de scripts. 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.

Lo que instala el paquete

npx @falcux/ai-first@latest init deja un hook, pero de git, no del agente: un pre-push que corre el detector antes de publicar y un flujo que lo corre en cada pull request. Cubre el mismo principio —lo que debe pasar siempre, automático— en el único punto que todas las herramientas comparten, que es el repositorio. Los hooks de este capítulo, los del agente, se siguen configurando a mano en cada herramienta: el paquete no instala ninguno. Qué escribe init está en Qué deja init en tu repo, y cómo se usa el punto de control, en Auditar en local y en CI.

---

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.