Anatomía de la carpeta .claude: Qué hace y por qué confunde
Si has buscado "anatomía de la carpeta .claude", probablemente intentas entender qué hace realmente esta carpeta, por qué confunde a la gente y qué partes merecen tu atención.
Un hilo de Reddit de marzo de 2026 lo dejó claro. Un desarrollador que había tenido problemas por convenciones de ubicación poco claras creó una hoja de referencia sobre la estructura del directorio .claude/, los eventos de hooks, settings.json, la configuración MCP, la estructura de skills y los umbrales de gestión de contexto.
La confusión central: Global vs. Nivel de proyecto
La mayor fuente de confusión es la diferencia entre el directorio global ~/.claude/ y el directorio a nivel de proyecto .claude/.
El directorio global está en tu carpeta personal y define comportamiento compartido. El directorio a nivel de proyecto vive dentro de un repositorio específico y sobreescribe o extiende la configuración global.
Convenciones de ubicación
Skills van en .claude/skills/. Cada skill tiene su propio directorio con un archivo SKILL.md.
Agentes van en .claude/agents/, no como archivos sueltos en la carpeta raíz.
Configuración vive en .claude/settings.json a nivel de proyecto o ~/.claude/settings.json globalmente.
Los hooks son operativos, no pasivos
El error más común es un matcher demasiado estrecho. Un hook PostToolUse que solo coincide con "Write" se pierde ediciones hechas con "Edit" o "MultiEdit".
Cuatro cosas que importan de verdad
1. Alcance — Global vs. nivel de proyecto es la primera decisión.
2. Convenciones de ubicación — Los skills necesitan SKILL.md, los agentes van en agents/.
3. Contenido vs. orquestación — Skills, agentes, configuración, hooks y MCP no son conceptos equivalentes.
4. Señales de deriva — La documentación cambia rápido. Si tu configuración deja de funcionar sin que la hayas modificado, verifica si las convenciones subyacentes cambiaron.
La carpeta .claude combina alcance, estructura y comportamiento. Una vez que internalizas este modelo de tres capas, deja de parecer desorden oculto y empieza a verse como un mapa de operaciones.