CLAUDE.md, Skills, MCPs y Hooks: Cuándo Usar Cada Uno

Mi CLAUDE.md global tenía 363 líneas. Lo bajé a 186. Claude empezó a trabajar mejor.

Pero esa no es la lección. La lección real es que 187 de esas 363 líneas no debían estar ahí en primer lugar. Estaban duplicando algo que ya existía — solo que yo no sabía dónde ponerlas.

Claude Code tiene 4 mecanismos para inyectar contexto. CLAUDE.md es el más conocido y por eso el más abusado. La gente lo usa como bolsa de basura: reglas, documentación, procedimientos, configuración, conventions, recetas, todo. Y después se queja de que Claude "se distrae" o "olvida cosas".

El problema no es Claude. El problema es no entender que cada mecanismo tiene un costo distinto y un caso de uso distinto.

Acá va la matriz que te ahorra el rebote.

---

Los 4 mecanismos en 1 frase cada uno

1. CLAUDE.md — Archivo markdown que Claude lee SIEMPRE al inicio de cada turno. Es contexto estático: quién sos, cómo trabajás, qué stack usás.

2. Agent Skills — Carpetas en .claude/skills/ con un SKILL.md que describe un procedimiento. Solo el frontmatter (~100 tokens) está visible siempre. El contenido completo carga on-demand cuando Claude decide que lo necesita.

3. MCP servers — Servidores externos que exponen tools (funciones ejecutables) a Claude. Sirven para conectar con sistemas externos: bases de datos, APIs, CRMs, analytics.

4. Hooks — Comandos shell que ejecuta el harness (no Claude) en respuesta a eventos: antes de una tool, después de un edit, al enviar un prompt. Sirven para enforcement automático.

Tres son contexto. Uno es automatización. Empezamos por ahí.

---

La tabla que cambia todo: costo en tokens por turno

Mecanismo	Cuándo carga	Costo aproximado
CLAUDE.md	Siempre, en cada turno	~500 tokens base + lo que tenga adentro
Skill (frontmatter)	Siempre visible	~100 tokens por skill
Skill (contenido)	Solo cuando Claude la invoca	0 hasta que se usa
MCP (schemas de tools)	En cada turno si está activo	~20-200 tokens por tool
Hook	Lo ejecuta el harness, no Claude	0 tokens base

Lectura:

• Un CLAUDE.md de 500 líneas te cuesta ~2500 tokens en cada turno de la conversación.
• 50 skills te cuestan ~5000 tokens fijos en frontmatter, pero solo cargás el contenido de la que necesitás en ese momento.
• 5 MCPs default sin optimización pueden meter 50k+ tokens fijos antes de empezar la conversación.
• Los hooks no cuestan nada de contexto: corren afuera.

Recomendación oficial de Anthropic (mayo 2026): CLAUDE.md menos de 200 líneas, techo ~300. Después de eso, la señal se diluye en ruido y Claude empieza a ignorar instrucciones.

---

La matriz decisional (esto es lo que vale el artículo)

Lo único que importa es esta tabla. Si la entendés, ya está.

Lo que necesitás	Mecanismo correcto	Por qué
"Quién soy, cómo trabajo, qué stack uso, tono, idioma"	CLAUDE.md	Lo necesitás siempre, en todas las conversaciones
"Cómo se hace X paso a paso (procedimiento repetible)"	Skill	On-demand, no carga si no se usa
"Conectar con un sistema externo (DB, API, CRM, analytics)"	MCP	Tools ejecutables, lazy loading con ToolSearch
"Enforcement automático (lint, format, validación pre-commit)"	Hook	Lo ejecuta el harness, 0 tokens de contexto
"Reglas que cambian según la carpeta del proyecto"	Path-scoped rules	Solo carga cuando edita archivos de esa área

Algunos ejemplos concretos de mi setup:

• CLAUDE.md global: "respondé en español, sos un arquitecto senior, usás voseo rioplatense, conventional commits". Esto lo necesito en todos los proyectos, siempre.
• Skill kb-note: "cómo investigar un link y cargar una nota en mi Knowledge Base de Obsidian con formato X". Esto lo uso 2 veces por semana, no tiene sentido que cargue siempre.
• MCP ghl: acceso directo a mi CRM Go High Level (contactos, pipeline, calendario). Una tool, no un texto.
• Hook pre-commit: corre npm run sync:design antes de cada commit para regenerar tokens visuales. Yo no decido si corre, el harness lo ejecuta solo.

Si querés ver cómo se conecta todo, hay un artículo donde armé un sistema con 20 agentes especializados usando exactamente estos 4 mecanismos.

---

5 anti-patterns que están matando tu setup

1. CLAUDE.md como wiki

El error: archivo de 800-2000 líneas con documentación del proyecto, conventions detalladas, ejemplos de código, snippets, FAQ, decisiones de arquitectura, todo.

Por qué duele: estás pagando esos 800-2000 líneas en cada turno de cada conversación. Y Claude empieza a ignorar partes porque la señal se diluye.

Solución:

• Lo conceptual (10-20%) se queda en CLAUDE.md
• Procedimientos repetibles → Skill (carga on-demand)
• Documentación de arquitectura → archivo markdown referenciado con @docs/architecture.md (imports recursivos hasta 5 niveles de profundidad)

2. MCPs siempre activos

El error: todos los MCPs habilitados por default. Google Analytics, Search Console, Meta, n8n, Excalidraw, Notion, todos cargados desde el primer turno.

Por qué duele: 5 MCPs con 10-20 tools cada uno = 50k-100k tokens fijos antes de escribir tu primer prompt. Tu ventana de contexto efectiva se reduce a la mitad.

Solución: sistema toggle on/off por proyecto. Yo tengo mcp on gsc, mcp on meta, mcp off n8n — solo activo lo que voy a usar en esa sesión. Los siempre-activos quedan en 3: context7 (docs), engram (memoria persistente), ghl (CRM del proyecto).

3. Skills como CLAUDE.md disfrazado

El error: crear una skill con descripción gigante y disable-model-invocation: false, esperando que Claude "lea esto siempre". Pero al estar en .claude/skills/, Claude la trata como skill: solo lee la descripción para decidir si invocarla.

Por qué duele: lo que querías que cargue siempre, carga a medias (la descripción) y nunca completo. Funciona peor que CLAUDE.md y peor que skill bien hecha.

Solución: si lo necesitás siempre → CLAUDE.md. Si lo necesitás a veces → skill con descripción corta y precisa (el contenido carga cuando se invoca).

4. Hooks para inyectar contexto

El error: usar un hook UserPromptSubmit para inyectar texto al contexto en cada turno ("recordá que…", "tené en cuenta…").

Por qué duele: los hooks generan stdout que va al contexto, llenando la ventana sin que vos te enteres. Y son frágiles: si el script falla, el contexto queda inconsistente.

Solución: los hooks son para enforcement automático, no para contexto. Validar antes de un commit, formatear después de un edit, ejecutar tests después de cambios en un archivo crítico. Si querés contexto persistente, usá CLAUDE.md o un sistema de memoria como Engram.

5. Sin jerarquía: un solo CLAUDE.md global para todo

El error: meter todo en ~/.claude/CLAUDE.md. El stack de React, las credenciales del proyecto Y, el idioma preferido, las reglas de copywriting del proyecto Z.

Por qué duele: cargás reglas del proyecto Z cuando estás trabajando en el proyecto X. Y al revés. Y el archivo crece sin control.

Solución: jerarquía clara.

~/.claude/CLAUDE.md          → persona genérica (siempre, todos los proyectos)
<proyecto>/CLAUDE.md         → recetas operacionales de ese proyecto
<proyecto>/CLAUDE.local.md   → overrides personales (gitignored)
<proyecto>/.claude/rules/    → reglas path-scoped (api/, frontend/, etc.)

Cada nivel carga solo cuando aplica. El global es persona. El de proyecto son recetas. Las rules son hiper-específicas.

---

Mi setup real (los números)

No es teoría. Esto es lo que corre en mi setup actual de marca personal:

~/.claude/CLAUDE.md                           186 líneas
  └─ persona, idioma, reglas de comunicación, jerarquía de herramientas

<proyecto>/CLAUDE.md                          155 líneas
  └─ stack, commands, architecture decisions, key files

<proyecto>/CLAUDE.local.md                    overrides personales (gitignored)
  └─ credenciales no sensibles, shortcuts, focus actual

Skills globales (~/.claude/skills/)           ~40 skills
  └─ GSD, SEO, Next.js, n8n, blog, métricas, video-editing

Skills por proyecto                           1-2 skills custom
  └─ ej: kb-note (cargar info en Knowledge Base)

MCPs default activos                          3 (context7, engram, ghl)
MCPs on-demand (toggle)                       5 (gsc, ga4, meta, n8n, excalidraw)
  └─ Script bash: mcp on/off <nombre>, requiere reiniciar Claude

Hooks                                         pre-commit (sync tokens visuales)
                                             dashboard-activity (PostToolUse, Stop)

Path-scoped rules                            4 archivos
  └─ api.md, blog.md, frontend.md, remotion.md

Observaciones:

• El CLAUDE.md global es persona. Casi nunca cambia.
• Los CLAUDE.md de proyecto son recetas. Los reviso cada 2-3 semanas porque envejecen rápido (stack actualizado, decisiones nuevas).
• Las skills son procedimientos. Las uso intensivo o no las uso. Las que llevan meses sin invocarse, las archivo.
• Los MCPs son conexiones. Solo los que necesito esa semana están activos.
• Los hooks son garantías. Corren solos, no los pienso.

---

Cómo auditar tu setup en 4 pasos

Si llegaste hasta acá, hacé esto este fin de semana. Te toma 40 minutos.

Paso 1: medí. Contá las líneas de cada CLAUDE.md que tenés.

wc -l ~/.claude/CLAUDE.md
fd CLAUDE.md ~/Desktop/Proyectos --exec wc -l

Si tenés alguno arriba de 300 líneas, hay material para mover.

Paso 2: clasificá. Tomá cada sección de tu CLAUDE.md grande y preguntale:

• ¿Lo necesito en CADA conversación? → se queda en CLAUDE.md
• ¿Es un procedimiento que se hace a veces? → va a Skill
• ¿Es acceso a un sistema externo? → va a MCP
• ¿Es enforcement que el harness puede hacer? → va a Hook

Paso 3: cortá. Lo que no entra en ninguna categoría, probablemente no debería existir. Borralo. Si lo extrañás en 2 semanas, lo agregás.

Paso 4: mantenelo. Pone un recordatorio cada 2-3 semanas para revisar. Tu CLAUDE.md se va a llenar de ruido si no lo podás.

---

FAQ

¿No es más simple meter todo en CLAUDE.md y listo? Más simple sí. Más caro también. La diferencia entre un setup amateur y uno arquitectónico no son las líneas — es saber qué va dónde. Pagar 5k tokens fijos por turno cuando podrías pagar 500 es la diferencia entre que Claude tenga ventana para tu código o no.

¿Skills reemplazan a CLAUDE.md? No. Resuelven cosas distintas. CLAUDE.md es "quién sos vos como colaborador". Skills son "cómo se hace X". Ninguno se come al otro.

¿Los MCPs son obligatorios? No, son opcionales. Si tu trabajo no requiere conectar Claude con sistemas externos (DBs, APIs, CRMs), no necesitás MCPs. Para desarrollo web puro, alcanza con CLAUDE.md + Skills.

¿Hooks son riesgosos? Pueden serlo si los configurás mal (corren shell con permisos amplios). Empezá con uno simple: pre-commit que corre tu linter. Después escalá.

¿Cuándo no usar nada de esto? Si tu uso de Claude es esporádico y de tareas únicas, no necesitás nada. CLAUDE.md, Skills, MCPs y Hooks tienen sentido cuando trabajás con un proyecto recurrente o un sistema persistente.

---

El punto

La pregunta no es "cuánto pongo en CLAUDE.md". Es "qué mecanismo corresponde a esto que quiero darle a Claude".

Cuatro mecanismos, cuatro costos, cuatro casos de uso. La diferencia entre que Claude trabaje rápido y enfocado, o lento y disperso, está en saber cuál es cuál.

Si tenés un CLAUDE.md gigante, no es porque sos prolijo. Es porque no estás usando los otros 3.

Empezá auditando.