Dónde viven tus Skills y CLAUDE.md en Claude Code

Tu configuración tiene más poder del que crees

Cuando empiezas a usar Claude Code, lo primero que descubres es que puedes escribir instrucciones en un archivo llamado CLAUDE.md. Pero a medida que avanzas, te das cuenta de que hay varios sitios donde pueden vivir esas instrucciones, y que los Skills tienen su propia lógica de ubicación.

Saber dónde colocar cada cosa es la diferencia entre un sistema organizado que escala contigo y un desorden de archivos duplicados que se contradicen entre sí. En este artículo te explico los niveles de configuración, dónde vive cada pieza y cómo compartir tus Skills entre proyectos y equipos.

Si todavía no tienes claro qué es un Skill y en qué se diferencia de CLAUDE.md, te recomiendo leer primero Skills vs. CLAUDE.md: cuándo usar cada uno.

Los 4 niveles de CLAUDE.md

Claude Code no lee un solo archivo de instrucciones. Lee varios, organizados por niveles. Todos se combinan (no se sobreescriben), así que puedes tener instrucciones en cada nivel sin que se anulen entre sí.

Qué va en cada nivel

Nivel usuario (~/.claude/CLAUDE.md): tus preferencias personales que aplican siempre. Por ejemplo: "Usa español con acentos correctos", "Mi nombre es Ana García", "Nunca borres archivos sin confirmar".

Nivel proyecto (./CLAUDE.md): las reglas del equipo. Estructura del proyecto, convenciones de código, herramientas que se usan, cómo se despliega. Todo lo que un nuevo colaborador necesitaría saber.

Nivel local (./CLAUDE.local.md): tus ajustes personales para un proyecto específico. Quizás prefieres un formato de salida diferente al del equipo, o tienes rutas locales distintas. Este archivo se añade al .gitignore automáticamente.

Nivel gestionado: solo aplica en organizaciones grandes donde el departamento de tecnología despliega políticas para todos los empleados. Si trabajas por tu cuenta, puedes ignorar este nivel.

Dónde viven los Skills

Los Skills tienen su propia estructura de carpetas, separada del CLAUDE.md. Cada Skill es una carpeta con un archivo SKILL.md dentro.

La diferencia clave: los Skills personales te siguen a todos tus proyectos. Los Skills de proyecto se comparten con tu equipo cuando subes el código al repositorio.

Un Skill puede contener más que solo el archivo SKILL.md. Puedes incluir plantillas, ejemplos y guiones auxiliares:

mi-skill/
  SKILL.md          # Instrucciones principales
  plantilla.md      # Plantilla que Claude completa
  ejemplos/         # Ejemplos de referencia

Cómo compartir Skills entre proyectos

Aquí es donde la organización marca la diferencia. Si creas un Skill útil en un proyecto y quieres usarlo en otros, tienes dos opciones.

Opción 1: Skills personales (la más sencilla)

Mueve el Skill a tu carpeta personal:

# Mover un Skill de proyecto a personal
mv .claude/skills/mi-skill ~/.claude/skills/mi-skill

A partir de ese momento, el Skill estará disponible en cualquier proyecto que abras con Claude Code.

Opción 2: Enlaces simbólicos (la más flexible)

Un enlace simbólico es como un acceso directo: el archivo vive en un solo lugar, pero puedes acceder a él desde varios sitios. Esto te permite mantener una única copia de tus Skills y enlazarla en cada proyecto.

# Crear la carpeta central de Skills
mkdir -p ~/.claude/skills/generar-informe
 
# Enlazar en tu proyecto
ln -s ~/.claude/skills/generar-informe .claude/skills/generar-informe

La ventaja: si actualizas el Skill en la carpeta central, todos los proyectos que lo enlazan reciben el cambio automáticamente.

Cómo compartir Skills con tu equipo

Compartir Skills entre máquinas o con compañeros de equipo es todavía más importante, porque asegura que todos trabajen con las mismas instrucciones.

Subir los Skills al repositorio

La forma más directa: incluye la carpeta .claude/skills/ en tu repositorio. Cuando un compañero clone el proyecto, recibirá los mismos Skills.

git add .claude/skills/
git commit -m "Añadir Skills compartidos del equipo"
git push

Usar un repositorio central de Skills

Si tienes Skills que aplican a varios proyectos de tu organización, puedes crear un repositorio independiente con todos ellos y enlazarlos en cada proyecto:

# Clonar el repositorio de Skills del equipo
git clone https://github.com/tu-equipo/skills-compartidos ~/skills-equipo
 
# Enlazar en cada proyecto
ln -s ~/skills-equipo/revisar-codigo .claude/skills/revisar-codigo

Sincronizar con tus archivos de configuración personales

Si gestionas tus archivos de configuración en un repositorio (lo que a veces se llama "dotfiles"), puedes incluir tu carpeta ~/.claude/ para que tu configuración de Claude Code se sincronice entre todas tus máquinas.

Guía paso a paso para organizar tu configuración

Si estás empezando o quieres poner orden en lo que ya tienes, sigue estos pasos:

1. Crea tu CLAUDE.md personal. Abre el archivo ~/.claude/CLAUDE.md y escribe 10 a 20 líneas con tus preferencias básicas: tu nombre, tu idioma preferido, reglas que siempre aplican.

2. Revisa el CLAUDE.md de tu proyecto. Si trabajas en equipo, asegúrate de que ./CLAUDE.md contenga las convenciones del proyecto. Si trabajas solo, úsalo para documentar la estructura y las herramientas que usas.

3. Identifica Skills repetitivos. Si le repites las mismas instrucciones a Claude en varias conversaciones, es momento de convertirlas en un Skill. Crea la carpeta en .claude/skills/ o en ~/.claude/skills/ según si es de proyecto o personal.

4. Decide qué compartir. Los Skills que solo tú usas van en ~/.claude/skills/. Los que benefician al equipo van en .claude/skills/ dentro del repositorio.

5. Usa enlaces simbólicos para evitar duplicados. Si un Skill aplica a varios proyectos pero no quieres que sea global, enlázalo desde una carpeta central.

El mapa completo

Para que quede claro de un vistazo:

~/.claude/                          # Tu configuración personal
  CLAUDE.md                         # Instrucciones para todos los proyectos
  skills/                           # Skills disponibles en todos los proyectos
    generar-informe/
      SKILL.md

tu-proyecto/                        # Un proyecto específico
  CLAUDE.md                         # Instrucciones del equipo
  CLAUDE.local.md                   # Tus ajustes personales (no se sube)
  .claude/
    skills/                         # Skills de este proyecto
      revisar-codigo/
        SKILL.md
    settings.json                   # Permisos y configuración

Configurar bien tus Skills y archivos CLAUDE.md es una inversión de 15 minutos que te ahorra horas de repetición. Una vez que lo haces, Claude Code trabaja como un asistente que realmente te conoce, sin que tengas que explicarle lo mismo en cada conversación.

En nuestros talleres de Claude Code dedicamos un bloque completo a diseñar esta estructura desde cero. Cada participante sale con su CLAUDE.md personal, sus primeros Skills y un sistema organizado para su flujo de trabajo. 8 horas, 100% práctico.