La carpeta .claude/ es donde vive todo el comportamiento de Claude Code en tu proyecto. Sin ella, Claude funciona con defaults genéricos. Con ella, definís hooks que corren automático, skills que invocás cuando querés, agents para tareas pesadas y settings de permisos. La estructura está documentada oficialmente por Anthropic en la doc de Claude Code y vive tanto en tu repo como en ~/.claude/ global. Para entender el archivo más importante adentro, primero leé sobre CLAUDE.md y ahorro de tokens. Y para los conceptos básicos antes de configurar nada, mirá el diccionario de Claude Code con 8 conceptos clave.
¿Qué es la carpeta .claude/?
.claude/ es el directorio de configuración de Claude Code. Adentro van los hooks, skills, agents, slash commands, plugins, output styles y settings que definen cómo Claude se comporta en ese proyecto. Es la diferencia entre Claude funcionando "por default" y Claude funcionando como vos querés.
Vive en dos lugares: en ~/.claude/ para tu config global (aplica a todos tus proyectos) y en la raíz del repositorio para config específica del proyecto. Las dos se combinan automáticamente cuando abrís una sesión, con la del proyecto pisando la global cuando hay conflicto.
¿Por qué importa?
- Comportamiento determinístico: los hooks corren siempre, sin depender del criterio del modelo. Si necesitás que algo se ejecute cada vez, va en un hook.
- Workflows reusables: las skills te dejan capturar un proceso una vez y reusarlo siempre. Pasás de explicar cómo se hace algo a invocarlo.
- Equipo alineado: la carpeta va a git. Todo tu equipo hereda los mismos hooks, skills y permisos. No hay que onboardear devs uno por uno.
La estructura completa de la carpeta
Esta es la anatomía de un .claude/ completo. No todos los proyectos necesitan todo, pero conviene saber qué entra dónde. Acá la cheat-sheet rápida antes del detalle:
| Path | Qué hace | ¿Va a git? |
|---|---|---|
CLAUDE.md | Reglas advisory en lenguaje natural | Sí |
CLAUDE.local.md | Tus overrides personales | No |
.mcp.json | Config de MCP servers | Sí |
.claude/hooks/ | Scripts shell deterministas | Sí |
.claude/commands/ | Slash commands custom | Sí |
.claude/skills/ | Workflows reusables | Sí |
.claude/agents/ | Subagents para tareas aisladas | Sí |
.claude/output-styles/ | Formatos de respuesta custom | Sí |
.claude/plugins/ | Plugins del marketplace o propios | Sí |
.claude/rules/ | Reglas que cargan por path | Sí |
.claude/settings.json | Permisos, modelo, hooks registrados | Sí |
.claude/settings.local.json | Tu config personal | No |
.claude/statusline | Script de la barra inferior | Sí |
Esta tabla la podés usar como referencia cuando estás armando una carpeta nueva. Más detalle de cada uno abajo. Si querés ver un ejemplo real funcionando, el repo clawd-skills tiene 69 skills de producción que podés clonar.
CLAUDE.md y CLAUDE.local.md
Los archivos de reglas en lenguaje natural. Lo que Claude lee como prompt permanente. CLAUDE.md va a git, CLAUDE.local.md queda en gitignore. Ambos viven en la raíz del proyecto, no adentro de .claude/. La distinción importa: las reglas del equipo en uno, tus overrides personales en el otro.
.mcp.json
La config de los MCP servers que se cargan al abrir Claude Code. Ahí declarás Supabase, Vercel, Notion, Figma o el MCP que sea, con sus credenciales. Va commiteado: el equipo entero usa los mismos MCP servers. Sin este archivo, no hay integración con servicios externos.
.claude/hooks/
Scripts shell que Claude ejecuta automáticamente en eventos del sistema. Los nombres son reservados: PostToolUse.sh corre después de cada herramienta, SessionStart.sh al abrir la sesión, PreCompact.sh antes de comprimir contexto. La diferencia con CLAUDE.md es clave: las reglas son advisory (el modelo decide), los hooks son deterministas (siempre corren).
.claude/commands/
Slash commands tuyos. Cada archivo Markdown es un comando: si tenés ship.md, podés ejecutarlo con /ship. Adentro escribís el prompt completo que Claude va a procesar. Es la forma más simple de capturar un workflow recurrente sin armarte una skill completa.
.claude/skills/
Workflows reusables y más estructurados. Cada skill es una carpeta con un SKILL.md adentro que describe cómo hacer una tarea (clonar un reel, generar un carrusel, transcribir audio). Las invocás cuando las necesitás. La diferencia con commands es que las skills pueden tener referencias, scripts y assets adicionales en la misma carpeta.
.claude/agents/
Subagents para tareas aisladas. Cada archivo Markdown define un agent que Claude principal puede invocar para delegar trabajo pesado: leer 50 archivos, buscar un patrón, generar un reporte. El agent corre en una sesión aparte y devuelve solo el resumen, así no te llena el contexto principal.
.claude/output-styles/
Formatos de respuesta custom. Si querés que Claude responda solo con código sin explicaciones, o solo con bullet points, o en algún tono específico, lo definís acá. Cada archivo es un preset que activás cuando lo necesitás.
.claude/plugins/
Plugins instalados desde el marketplace o creados por vos. Un plugin bundlea skills, hooks, agents y commands juntos en una unidad reusable. Cuando instalás superpowers, por ejemplo, te aparece una carpeta acá con todas sus skills y hooks asociados.
.claude/rules/
Reglas que cargan condicionalmente según el path donde estés trabajando. Si tenés un monorepo y querés reglas distintas según editás apps/web/ o apps/api/, van acá. Cada archivo declara qué glob de paths lo activa.
settings.json y settings.local.json
La config estructurada en JSON. Permisos, allowlist de comandos, modelo default, MCP servers registrados, variables de entorno. settings.json va al equipo (git), settings.local.json es tu config personal (gitignored). Es donde definís que npm install no te pregunta confirmación.
statusline
Script que define qué muestra la barra de estado en la parte inferior de Claude Code. Podés meterle el branch de git, el modelo activo, el costo acumulado o lo que se te ocurra. Pequeño pero útil para tener feedback constante de la sesión.
Cómo armarla paso a paso
Paso 1 — Creá el esqueleto base
Desde la raíz de tu proyecto:
mkdir -p .claude/{hooks,commands,skills,agents}
touch .claude/settings.json
Eso te deja la estructura mínima. No hace falta crear todas las subcarpetas de una: las podés ir sumando a medida que las necesités.
Paso 2 — Configurá settings.json
La base mínima útil es allow-listar comandos comunes para que Claude no te pregunte cada vez:
{
"permissions": {
"allow": [
"Bash(git status:*)",
"Bash(git diff:*)",
"Bash(npm install:*)",
"Bash(ls:*)"
]
},
"model": "claude-opus-4-7"
}
Eso solo te ahorra cientos de prompts de confirmación a lo largo del mes.
Paso 3 — Sumá tu primer hook
Empezá simple. Un SessionStart.sh que cargue contexto del proyecto al abrir la sesión:
#!/bin/bash
echo "Branch: $(git branch --show-current)"
echo "Last commit: $(git log -1 --oneline)"
git status --short
Hacelo ejecutable con chmod +x .claude/hooks/SessionStart.sh y listo. Cada vez que abras Claude en ese proyecto, vas a tener el estado del repo sin tener que pedirlo.
Paso 4 — Agregá skills y commands tuyos
Empezá con un slash command simple. Creá .claude/commands/ship.md:
Buildea, lintea y deploya el proyecto en este orden:
1. npm run build
2. npm run lint
3. git push origin main
Si algo falla, parar y mostrarme el error.
Lo ejecutás con /ship. Las skills más complejas las podés organizar como carpetas con su propio SKILL.md y assets.
Paso 5 — Versionalo en git
Agregá .claude/ al repo (sin los .local.json):
# .gitignore
*.local.*
Commiteá. Ahora cada dev del equipo que clone el repo hereda los hooks, skills y settings. La parte personal de cada uno queda en ~/.claude/ o en archivos con sufijo .local.json.
Resumen
.claude/es el directorio que define el comportamiento de Claude Code en tu proyecto.- Tiene dos sabores: global en
~/.claude/para config compartida entre proyectos y local en la raíz del repo para config específica. - Adentro: hooks (deterministas), skills (workflows que invocás), agents (tareas pesadas aisladas), commands (slash custom), plugins (bundles), settings.json (permisos y modelo).
- Empezá chico: settings.json + un SessionStart.sh + un par de slash commands. Crece a medida que descubrís qué necesitás.
- Versionalo en git para que tu equipo herede el setup. Los
.local.jsonquedan personales.
La carpeta .claude/ es la diferencia entre Claude Code corriendo en automático y Claude Code corriendo como vos querés.
Preguntas frecuentes sobre .claude folder
La carpeta .claude/ es el directorio donde Claude Code guarda toda la configuración específica del proyecto: hooks que se disparan automáticamente, skills reusables, subagents para tareas aisladas, slash commands custom, plugins, output styles y settings de permisos. Vive en la raíz de tu repositorio o en ~/.claude/ para configuración global. Cada vez que abrís Claude Code, este levanta lo que encuentra ahí adentro y lo aplica a la sesión. Sin esa carpeta, Claude funciona con defaults genéricos: no tenés hooks, no tenés skills propias y cada sesión arranca con el mismo comportamiento. La documentación oficial de Anthropic la describe como el "punto único" de configuración. Para entender el archivo más importante adentro, leé la guía de CLAUDE.md y ahorro de tokens.
Tenés dos carpetas .claude/ que conviven y se combinan. La global vive en ~/.claude/ y aplica a todas tus sesiones, sin importar el proyecto: ahí van skills universales, agents que querés usar siempre y settings personales. La del proyecto vive en la raíz del repositorio (junto al package.json o pyproject.toml) y solo aplica cuando abrís Claude Code en ese directorio: ahí van reglas específicas del stack, hooks que tienen sentido solo para ese código y comandos del proyecto. Claude las merge automáticamente: lo del proyecto pisa lo global cuando hay conflicto. La regla práctica es que skills y agents reusables van en global, mientras que hooks y reglas específicas van en proyecto. Más detalles en cosas que hacer antes de abrir Claude Code.
Los hooks son scripts shell que Claude Code ejecuta automáticamente en momentos específicos: antes o después de usar una herramienta, al arrancar una sesión, antes de compactar el contexto. Viven en .claude/hooks/ con nombres reservados como PostToolUse.sh, SessionStart.sh o PreCompact.sh. A diferencia de las reglas en CLAUDE.md (que son advisory: el modelo decide si las respeta), los hooks son deterministas: siempre corren. Sirven para tareas que no podés delegar al criterio del modelo, como auto-commitear después de cada edit, cargar contexto crítico al abrir la sesión o guardar estado antes de comprimir. Si tu workflow tiene un paso que tiene que pasar sí o sí cada vez, ese paso va en un hook. La doc de hooks lista todos los eventos disponibles.
Skills y subagents resuelven problemas distintos. Una skill es un workflow reusable que vos invocás cuando lo necesitás: un archivo Markdown que describe cómo hacer una tarea (clonar un reel, generar un carrusel, transcribir audio). Vive en .claude/skills/ y se carga cuando la pedís explícitamente. Un subagent en cambio es una sesión aislada de Claude que delegás para una tarea pesada: lee 50 archivos, busca un patrón, escribe un reporte y devuelve solo el resumen. Vive en .claude/agents/ y lo usa Claude principal para no saturar su propio contexto. La regla rápida: si querés un workflow paso a paso, hacé skill. Si querés que algo se ejecute en paralelo sin contaminar tu contexto principal, hacé agent. Más en el diccionario de Claude Code.
Claude Code crea la carpeta .claude/ automáticamente la primera vez que la usás, pero solo con lo mínimo (un settings.json casi vacío). Todo lo demás (hooks, skills, agents, commands) lo armás vos a medida que descubrís qué necesitás. Hay dos atajos para no arrancar de cero. El primero es instalar plugins desde el marketplace: /plugin install te trae carpetas enteras de skills y hooks ya configurados (por ejemplo el plugin superpowers mete brainstorming, TDD y debugging). El segundo es copiar carpetas de otros devs: si encontrás un repo con .claude/skills/ que te gusta, podés clonarlas y adaptarlas. La mayoría de los devs serios mantienen su .claude/ en un repo aparte como clawd-skills y la symlinkean a sus proyectos.
settings.json es el archivo de configuración estructurada de Claude Code. Adentro definís permisos (qué herramientas puede usar sin preguntarte, qué comandos están en allowlist), modelo default, hooks registrados, MCP servers que se cargan, variables de entorno y configuración de cada plugin instalado. Hay dos versiones: settings.json (va a git, configuración del equipo) y settings.local.json (gitignored, tu config personal). Si no querés que Claude te pregunte cada vez antes de correr npm install o git status, los agregás al allowlist en este archivo y listo. El archivo soporta merge entre global, proyecto y local: lo más específico gana. Es el equivalente al package.json pero para tu setup de Claude Code. Más detalles en la doc oficial de settings.
Fuentes e inspiración
Mirá los posts originales donde desarrollamos estas ideas en redes.
