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

Mi CLAUDE.md global había crecido hasta mezclar identidad, reglas, procedimientos y conexiones. Lo reduje y Claude empezó a recibir una señal más clara.

Pero esa no es la lección. La lección real es que gran parte de ese contenido no debía estar ahí. Estaba duplicando algo que ya existía — solo que yo no sabía dónde ponerlo.

Claude Code tiene 4 mecanismos para inyectar contexto o aplicar comportamiento. 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 con contexto persistente del proyecto: quién sos, cómo trabajás, qué stack usás y qué reglas generales debe respetar Claude.

2. Agent Skills — Carpetas en .claude/skills/ con un SKILL.md que describe un procedimiento. 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 y 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 aportan contexto o capacidad. Uno es automatización. Empezamos por ahí.

La tabla que cambia todo: costo operativo

Mecanismo	Cuándo participa	Costo que conviene vigilar
CLAUDE.md	En el contexto general del proyecto	Ruido persistente e instrucciones obsoletas
Skill	Cuando la tarea coincide con su propósito	Mantenimiento del procedimiento y calidad del trigger
MCP	Cuando se habilita una conexión externa	Permisos, schemas, superficie de riesgo y mantenimiento
Hook	Cuando ocurre el evento configurado	Tiempo de ejecución, fallos del script y bloqueo del flujo

Lectura:

Un CLAUDE.md largo carga información aunque la tarea no la necesite.
Las skills permiten separar procedimientos y cargarlos cuando corresponden.
Los MCPs agregan capacidad, pero también permisos y superficie de mantenimiento.
Los hooks aplican reglas fuera del razonamiento del modelo.

No hay un umbral universal de líneas o tokens que convierta un archivo en “demasiado largo”. La señal es otra: si el contenido no cambia el comportamiento en la mayoría de las tareas, probablemente está en la capa equivocada.

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, analytics)"	MCP	Tools ejecutables para consultar o actuar
"Enforcement automático (lint, format, validación pre-commit)"	Hook	Lo ejecuta el harness, sin depender de que Claude lo recuerde
"Reglas que cambian según la carpeta del proyecto"	Path-scoped rules	Solo carga cuando edita archivos de esa área

Algunos ejemplos concretos:

CLAUDE.md global: idioma, reglas de comunicación y guardrails de Git que aplican a todos los proyectos.
Skill editorial: cómo investigar, redactar y mantener un artículo como borrador hasta recibir aprobación.
MCP de analytics: acceso directo a datos externos cuando una tarea necesita consultarlos.
Hook pre-commit: corre una regeneración o comprobación obligatoria antes de aceptar un commit.

Si querés ver por qué una capa adicional no siempre mejora el sistema, la retrospectiva del orquestador multiagente retirado explica qué construí, qué eliminé y qué criterio sobrevivió.

5 anti-patterns que están matando tu setup

1. CLAUDE.md como wiki

El error: archivo enorme con documentación del proyecto, conventions detalladas, ejemplos de código, snippets, FAQ y decisiones de arquitectura.

Por qué duele: pagás ese contexto en tareas que no lo necesitan. Y Claude puede empezar a ignorar partes porque la señal se diluye.

Solución:

Lo conceptual y estable se queda en CLAUDE.md
Procedimientos repetibles → Skill (carga on-demand)
Documentación de arquitectura → archivo markdown referenciado

2. MCPs siempre activos

El error: todos los MCPs habilitados por default, aunque la sesión no vaya a usarlos.

Por qué duele: cada conexión amplía el catálogo de herramientas, los permisos y la superficie de riesgo antes de empezar la tarea.

Solución: sistema toggle on/off por proyecto. Solo activá lo que vas a usar en esa sesión. Las conexiones permanentes deberían ser las mínimas que el trabajo recurrente justifica.

3. Skills como CLAUDE.md disfrazado

El error: crear una skill con descripción gigante, esperando que Claude "lea esto siempre". Pero al estar en .claude/skills/, Claude la trata como skill: usa la descripción para decidir si invocarla.

Por qué duele: lo que querías que cargue siempre, carga a medias y nunca completo. Funciona peor que CLAUDE.md y peor que una 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.

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 pueden agregar salida al contexto sin que sea evidente. 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, regenerar después de un cambio o bloquear una operación peligrosa.

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         → contexto y reglas de ese proyecto
<proyecto>/CLAUDE.local.md   → overrides personales (gitignored)
<proyecto>/.claude/rules/    → reglas path-scoped

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

Qué sobrevivió al retirar el orquestador

No es teoría. Construí una organización permanente de agentes y unos meses después la eliminé porque no tenía uso real suficiente para justificar su coordinación.

Sobrevivió este setup más simple:

CLAUDE.md
  └─ stack, comandos, restricciones y rutas clave

Skills
  └─ procedimientos reutilizables cargados por necesidad

MCPs
  └─ conexiones externas activadas para tareas concretas

Hooks
  └─ guardrails automáticos

Trabajo directo
  └─ opción por defecto cuando otra capa no aporta valor

Observaciones:

El CLAUDE.md global es persona. Casi nunca cambia.
Los CLAUDE.md de proyecto son contexto y reglas. Envejecen cuando cambia el stack o una decisión.
Las skills son procedimientos. Si no resuelven una tarea recurrente, no necesitan permanecer activas.
Los MCPs son conexiones. Solo deben habilitarse cuando una tarea necesita esa capacidad.
Los hooks son garantías. Deben ser acotados, observables y reversibles.

Cómo auditar tu setup en 4 pasos

Si llegaste hasta acá, hacé esto antes de agregar otra capa.

Paso 1: medí. Revisá el tamaño y, sobre todo, el uso real de cada archivo de instrucciones.

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

Un archivo largo no es un error por sí mismo. El problema aparece cuando acumula material que no cambia el comportamiento o duplica otra fuente.

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. Eliminá duplicaciones y restaurá solo lo que demuestre utilidad.

Paso 4: mantenelo. Revisalo cuando cambien el proyecto, los permisos o el flujo. Una cadencia fija no reemplaza una señal real de obsolescencia.

FAQ

¿No es más simple meter todo en CLAUDE.md y listo? Más simple al principio, sí. Pero el costo aparece cuando reglas, procedimientos y documentación compiten por atención y envejecen en el mismo archivo.

¿Skills reemplazan a CLAUDE.md? No. Resuelven cosas distintas. CLAUDE.md es contexto general. 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, no necesitás MCPs. Para muchas tareas alcanza con instrucciones claras y skills.

¿Hooks son riesgosos? Pueden serlo si los configurás mal, porque ejecutan shell con permisos del entorno. Empezá con un guardrail simple, observable y fácil de revertir.

¿Cuándo no usar nada de esto? Si tu uso de Claude es esporádico y de tareas únicas, no necesitás una capa permanente. La solución directa puede ser la más sólida.

El punto

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

Contexto, procedimientos, conexiones y enforcement tienen costos distintos. La diferencia entre que Claude trabaje enfocado o disperso está en saber cuál corresponde.

Empezá auditando.