CLAUDE.md vs AGENTS.md vs SKILL.md: ¿Qué va dónde y por qué?

Cualquiera que comience a usar Claude Code tiende a crear un CLAUDE.md y poner todo en él: configuración del proyecto, reglas de codificación, normas para las solicitudes de integración, detalles de la tecnología utilizada y notas de inducción. Luego entra en juego AGENTS.md, seguido por SKILL.md, y parece que se necesitan tres archivos para la misma tarea. Pero no es así. Mezclarlos implica pagar por tokens que en realidad no sirven para nada.

Un modelo mental rápido

Imagínese una empresa. CLAUDE.md es el manual del empleado que cada nuevo trabajador lee desde el primer día, siempre presente de fondo. AGENTS.md es ese mismo manual, redactado de modo que los contratistas externos de cualquier agencia puedan seguirlo, no solo el personal permanente. SKILL.md es un manual en una estantería que solo se toma cuando se realiza esa tarea específica. Tres archivos, tres funciones y tres patrones de carga.

CLAUDE.md: siempre cargado

Este es el archivo de configuración principal de Claude Code. Al inicio de la sesión, Claude lo lee y lo mantiene en su prompt del sistema. Se carga una sola vez, pasa a formar parte del contexto utilizado durante toda la sesión y no es necesario recuperarlo del disco con cada mensaje. Así, cuando escribes un saludo, esas instrucciones ya están presentes, y vuelven a estarlo cuando más tarde pides una corrección de error.

La consecuencia es que un archivo grande ocupa permanentemente parte de la ventana de contexto, incluso en tareas donde la mayor parte de su contenido es irrelevante. Por eso resulta beneficioso contar con un archivo breve y enfocado.

Tres niveles

Las instrucciones provienen de varios ámbitos y se combinan:

1. Un archivo personal en ~/.claude/CLAUDE.md, que contiene preferencias aplicables a todos los proyectos, como el estilo de sangría o las costumbres en los mensajes de commit. Los compañeros del equipo nunca lo ven.

Un archivo del proyecto, ya sea .claude/CLAUDE.md o uno en la raíz del repositorio. Se guarda en Git, por lo que todos quienes clonen el repositorio reciben las mismas reglas. Aquí se incluyen detalles del entorno, comandos y estándares del equipo.

Reglas específicas para cada ruta, almacenadas en .claude/rules/ con una configuración de rutas en el frontmatter. Por ejemplo, un archivo de reglas de pruebas solo puede cargarse mientras se editan los archivos de prueba, lo que evita que la información irrelevante interfiera con el contexto.

Las instrucciones más específicas del proyecto se cargan después de las indicaciones generales a nivel de usuario, por lo que cuando hay conflicto entre ambas, la versión del proyecto puede prevalecer. La regla práctica es: los gustos personales se incluyen en la configuración personal, mientras que las convenciones compartidas por el equipo se definen en el proyecto.

Qué debe contenerse

Sé breve. Mantenerse por debajo de unas 200 líneas es un objetivo razonable, aunque se trata de una guía y no de un límite estricto. Incluye solo lo que Claude necesita en cada tarea: la pila tecnológica, los comandos para ejecutar pruebas y iniciar el servidor de desarrollo, reglas absolutas como nunca registrar datos de usuarios, y las principales decisiones arquitectónicas.

Omite todo lo específico de la tarea. Una guía extensa para revisar una PR o un catálogo de casos límite tienen un lugar más adecuado, que se menciona a continuación.

Un detalle importante

Si editas CLAUDE.md durante una sesión en curso, esta no se dará cuenta. El archivo se leyó una vez al inicio, por lo que se requiere una nueva sesión para que los cambios surtan efecto. Este es el motivo más común por el cual una regla recién añadida parece ignorada.

AGENTS.md: para equipos con varias herramientas

AGENTS.md cumple la misma función, albergando el contexto y las instrucciones del proyecto. Lo que difiere es quién puede leerlo: Claude Code lee CLAUDE.md, mientras que OpenAI Codex, Cursor, Gemini CLI y GitHub Copilot leen AGENTS.md.

Según lo descrito, Claude Code no reconoce automáticamente AGENTS.md, pero un enlace simbólico resuelve este problema al dirigir ambos nombres hacia el mismo archivo (verifique la documentación actual en caso de que haya cambios en su soporte):

ln -s AGENTS.md CLAUDE.md

Ahora hay un único archivo; todas las herramientas lo leen y nada se desvía.

Cuándo es necesario

Si todo el equipo utiliza únicamente Claude Code, CLAUDE.md es suficiente. Si las personas usan una combinación de herramientas, o si CI ejecuta un agente diferente al que los desarrolladores usan localmente, AGENTS.md se convierte en tu única fuente de verdad para todas ellas.

Pérdida silenciosa de instrucciones

Los pipelines de múltiples agentes presentan un modo de fallo problemático. Imagine que una etapa se ejecuta en Claude Code y otra en una herramienta de otro proveedor. Si sus reglas solo se encuentran en CLAUDE.md, la segunda herramienta las ignora sin generar ningún error ni advertencia. El agente funciona normalmente, pero no sigue las convenciones que usted asumía estaban en vigor. El resultado es inconsistente, el comportamiento varía, y como nada parece estar roto, resulta difícil identificar la causa. Utilizar AGENTS.md como referencia compartida permite que todas las herramientas del pipeline vean las mismas reglas.

SKILL.md: se carga bajo demanda

Este funciona de manera diferente. Los otros dos se cargan al inicio de cada sesión y permanecen en el contexto. Una habilidad solo se carga cuando la tarea actual coincide con su descripción.

Una habilidad es una carpeta que contiene un SKILL.md. El archivo comienza con un breve encabezado en YAML que le da a la habilidad un nombre y una descripción de una sola línea, y esa descripción es la que Claude lee para determinar si la habilidad es adecuada. Cuando envías un mensaje, Claude lo compara con las descripciones de todas tus habilidades y carga la que coincida. Cuando la tarea termina, la habilidad se descarta. Así es como puede verse el frontmatter:

---
name: pr-review
description: Use when the user asks to review a pull request or check code quality.
allowed-tools: [Read, Grep, Glob]
---

Por qué eso ahorra tokens

Supongamos que has documentado diez flujos de trabajo. Coloca los diez en CLAUDE.md y todos se cargarán con cada mensaje, incluso con una solicitud para corregir un error tipográfico. Como habilidades, solo se carga la relevante y las otras nueve no cuestan nada. En sesiones largas que combinan diferentes tipos de tareas, esto mantiene el contexto ligero y enfocado en el trabajo que tienes por delante.

La descripción es lo más importante

Claude depende de la descripción para tomar decisiones. Una vaga como “ayuda con código” o bien nunca se activará o lo hará para todo. Una precisa, como revisar solicitudes de pull en Python en busca de vulnerabilidades como inyección SQL o secretos codificados, se activará de manera fiable y solo cuando sea relevante. El nombre de la carpeta es para ti; la descripción es para Claude, así que escríbela pensando en él.

Dos opciones útiles de frontmatter

allowed-tools limita lo que puede hacer Claude mientras la habilidad está activa. Para una habilidad que explora un código, establecerla en leer, grep y glob permite a Claude inspeccionar sin editar ni escribir archivos, y la restricción se aplica incluso si se solicita una edición.

context: fork ejecuta el trabajo de la habilidad en un contexto aislado. Los pasos intermedios permanecen ocultos y solo el resultado final vuelve a la sesión principal, lo cual es adecuado para tareas que generan mucho contenido que no es necesario leer, como escanear cincuenta archivos para obtener un resumen.

Mantén también las habilidades compactas

Una habilidad grande consume más contexto una vez cargada. Si un flujo de trabajo necesita documentación extensa, ejemplos o material de referencia, colócalos en archivos separados y haz que la habilidad los invoque según sea necesario. Las instrucciones principales deben permanecer en el propio flujo de trabajo.

Comparación de los tres

Cómo elegir

• Una regla que se aplica a todas las tareas en cada sesión debe ir en CLAUDE.md.
• Si el equipo utiliza varias herramientas de programación con IA, o si el flujo de trabajo combina estas herramientas, haga que AGENTS.md sea la fuente de información fiable y enlace CLAUDE.md a él.

Un flujo de trabajo específico que repites, como revisar PRs, crear un currículum o buscar documentación, debería convertirse en una habilidad.

Si Claude debe permanecer en modo solo lectura para un flujo de trabajo, conviértelo en una habilidad con allowed-tools.

Si deseas activar algo manualmente con un comando, utiliza un comando de barra diagonal en .claude/commands/.

Un diseño ordenado

your-project/
├── AGENTS.md                   <- shared source of truth for all tools
├── CLAUDE.md                   <- imports AGENTS.md, adds Claude-specific rules
├── .claude/
│   ├── rules/
│   │   ├── testing.md          <- loads only when editing test files
│   │   └── security.md         <- loads only when editing auth-related files
│   ├── skills/
│   │   ├── pr-review/
│   │   │   └── SKILL.md        <- loads when you ask for a PR review
│   │   └── latex-resume/
│   │       └── SKILL.md        <- loads when you ask to build a resume
│   └── commands/
│       └── standup.md          <- /standup generates your daily update
└── ~/.claude/
    └── CLAUDE.md               <- your personal preferences, not in the repo

CLAUDE.md se mantiene breve porque solo contiene lo que realmente necesita cada tarea. Las habilidades se encargan de los flujos de trabajo complejos y específicos de cada tarea. AGENTS.md asegura que todo siga funcionando cuando un compañero cambia de herramientas.

Regla práctica

Si CLAUDE.md supera las 200 líneas, o aproximadamente entre 1,200 y 1,500 tokens, es probable que estés pagando por instrucciones que no necesitas en la mayoría de los mensajes. Ordena las instrucciones según cuándo se necesitan: “siempre” significa CLAUDE.md, “en diferentes herramientas” significa AGENTS.md, y “solo para un tipo de tarea” significa una habilidad. Tu ventana de contexto es como un presupuesto: el archivo principal consume parte de él en cada mensaje, mientras que las habilidades solo lo consumen cuando se utilizan, así que diseña la estructura en función de eso.

Lecturas relacionadas

• Explicación de los subagentes de Claude Code: qué son y cuándo usarlos — Cómo difieren los subagentes de Claude Code de las habilidades y los equipos de agentes: aislamiento de contexto, un primer subagente personalizado, buenas prácticas para descripciones y herramientas, y cuándo omitirlos.
• Equipos de agentes de Claude Code: cuándo utilizar múltiples agentes y cómo hacerlo — Cuándo basta con un solo agente, cuatro motivos para añadir más, patrones de orquestación, estilos de comunicación, ocho modos de fallo y la opción entre versión nativa e implementación propia para los equipos de Claude Code.

GPT-Image-2.5 Flare vs Sunburst: ¿Qué variante usar y cuándo? — Una comparación práctica de GPT-Image-2.5 Flare y Sunburst: puntuaciones en Arena, latencia, resultados de seguridad, precios, límites de calidad y qué variante se adapta a cada flujo de trabajo.

Reducir un CLAUDE.md gigante en un 91% y medir qué se dañó — Dividir un CLAUDE.md de 194K caracteres en habilidades, referencias y reglas específicas por ruta, verificar que no se perdió nada y medir con qué frecuencia se activan realmente las habilidades.