AGENTS.md vs CLAUDE.md vs SKILL.md: ¿qué archivo para qué agente? Lo que dice la investigación (2026)
¿De verdad archivos como AGENTS.md / CLAUDE.md ayudan a los agentes de programación? Un estudio de 2026 responde: sí, pero apenas, y escribirlos largos sale mal. En muchos agentes y modelos, los archivos de contexto no mejoraron de forma fiable el éxito de las tareas, mientras que el costo de inferencia subió más del 20%. La solución no es tirar el archivo, sino escribirlo breve (comandos de test/build, reglas que no se deben romper, rutas clave) y empujar el resto a archivos que se cargan bajo demanda, al estilo de divulgación progresiva.
- Las cifras de la investigación y el estado de las herramientas (AGENTS.md como estándar multiherramienta, sintaxis de import) se contrastaron con las fuentes al momento de escribir; estas herramientas cambian rápido, así que verifica la documentación actual.
AGENTS.md y CLAUDE.md, ¿son lo mismo?
En esencia son la misma idea: un archivo que el agente lee para aprender las convenciones del proyecto, solo que con un nombre distinto por herramienta. CLAUDE.md es la convención de Claude Code. AGENTS.md es el estándar multiherramienta en ascenso: lo leen Codex CLI, Copilot CLI, Gemini CLI, Cursor y también Claude Code.
Ambos hacen el mismo trabajo: darle al agente un briefing persistente que sobrevive entre sesiones de chat, para que no vuelva a preguntar tus convenciones cada vez. La única diferencia que vale la pena recordar: CLAUDE.md conserva algunas capacidades propias de Claude Code que AGENTS.md no estandariza, sobre todo la carga jerárquica y los imports. Para aprender a escribir un CLAUDE.md de principio a fin con una plantilla, mira la guía de CLAUDE.md.
Una línea para no confundir tres parecidos: AGENTS.md (el estándar de archivo) es distinto de AgentKit (el kit para Claude Code, agentkit.best) y de OpenAI AgentKit (Agent Builder/ChatKit).
AGENTS.md vs CLAUDE.md vs SKILL.md: ¿qué archivo hace qué trabajo?
AGENTS.md y CLAUDE.md ya no son el único archivo de proyecto que lee un agente. SKILL.md es un tipo de archivo totalmente distinto: una carpeta que contiene un archivo SKILL.md (frontmatter YAML con name/description, más un cuerpo en Markdown, opcionalmente junto a scripts/, references/ o assets/) que empaqueta una capacidad reutilizable y bajo demanda, no un contexto siempre cargado. El agente compara la tarea con la description de la skill y la carga solo cuando es relevante (o la invocas de forma explícita). Anthropic creó el formato para Claude Code (oct 2025) y lo publicó como el estándar abierto Agent Skills (agentskills.io); Codex lo adoptó en pocas semanas: la propia documentación de OpenAI confirma que en Codex "skills build on the open agent skills standard" (learn.chatgpt.com/docs/build-skills).
La diferencia con AGENTS.md/CLAUDE.md es de tipo, no solo de nombre. AGENTS.md y CLAUDE.md son contexto persistente, siempre cargado: justo lo que mide la investigación de abajo, y justo por qué inflarlos cuesta más del 20% de inferencia. SKILL.md se carga bajo demanda, solo cuando la tarea coincide: el modelo de divulgación progresiva que la sección posterior toma prestado como técnica de escritura. Ahora sabes por qué funciona esa técnica: es literalmente cómo las skills evitan gastar contexto en capacidades que no estás usando ahora mismo.
Los tres archivos también difieren en quién los lee, qué formato usan y para qué sirven:
| AGENTS.md | CLAUDE.md | SKILL.md | |
|---|---|---|---|
| ¿Siempre cargado? | Sí | Sí | No, bajo demanda |
| Quién lo lee | Codex, Copilot CLI, Gemini CLI, Cursor, Claude Code | Solo Claude Code | Solo Claude Code + Codex |
| Formato | Markdown simple | Markdown + imports @path | Frontmatter YAML + Markdown, scripts/refs opcionales |
| Ideal para | Convenciones de proyecto multiherramienta | Configuración propia de Claude Code | Un flujo de trabajo o capacidad reutilizable |
Un dato que conviene decir con claridad: Codex lee AGENTS.md; no lee CLAUDE.md en absoluto. Si Codex está en tu conjunto de herramientas, AGENTS.md es el archivo que de verdad ve; mira la mecánica de configuración de AGENTS.md en Codex para el orden de carga completo. Para cómo carga Codex las skills en concreto, mira cómo funcionan las Codex Skills.
Elección rápida: ¿necesitas que el agente sepa siempre tus comandos de test/build y las reglas que no se pueden romper? Usa AGENTS.md (o CLAUDE.md en Claude Code). ¿Necesitas una capacidad reutilizable que solo activas de vez en cuando, un flujo o un paquete de scripts? Entonces usa SKILL.md.
Lo que halló la investigación: ayuda, pero apenas
La pregunta de "si los archivos de contexto ayudan de verdad" ya tiene datos. El estudio "Evaluating AGENTS.md", de Gloaguen et al. (enviado en feb 2026) midió archivos de contexto en muchos agentes, modelos y repositorios. Los resultados merecen una pausa:
- Sin mejora general en el éxito de las tareas, cierto para ambos: archivos generados por LLM y archivos commiteados por desarrolladores. Eso va en contra de la recomendación habitual.
- El costo de inferencia subió más del 20% en promedio.
- Los resúmenes del repositorio, populares y recomendados por los proveedores de modelos, no ayudaron. En cambio, las instrucciones dentro de un archivo de contexto sí fueron seguidas correctamente por los agentes.
Algo que suele exagerarse: no es que "los archivos escritos por desarrolladores sean mejores". El estudio halló que ninguno de los dos tipos mejora el éxito de forma fiable. Pero como las instrucciones sí se siguen y los resúmenes no, la conclusión práctica es tajante: recorta el relleno de resumen y quédate con las instrucciones accionables. Archivo más pequeño, mismo éxito, menor costo.
La paradoja: el agente obedece con demasiado entusiasmo
Lo interesante es que el agente no ignora las instrucciones, sino que las sigue un poco con demasiado entusiasmo. Menciona tests y correrá más tests. Menciona herramientas y usará más herramientas. Menciona flujos propios del repositorio y explorará más.
El problema es que muchas de esas instrucciones no ayudan a resolver la tarea más rápido, solo la vuelven más pesada. Cada línea que añades es otra línea que el agente siente que "debe" cumplir. Por eso un archivo inflado quema tokens y alarga la tarea sin un resultado mejor.
Así que AGENTS.md no está mal; lo que está mal es cómo lo escribimos
La conclusión no es "deshazte del archivo de contexto". Es: no conviertas AGENTS.md en un manual de 2.000 palabras que el agente relea cada vez que arregla un bug.
Conserva las partes accionables:
- El comando de test, el comando de build, el comando de ejecución.
- Las reglas que no se deben romper (no cambiar la API pública, no tocar el directorio X…).
- Las rutas / directorios importantes.
Luego deja que el agente averigüe el resto. Sin rodeos: si atamos a los agentes demasiado a nuestro propio conocimiento, terminarán… tan tontos como nosotras. Dales algo de espacio para volar y después vuelve a guiarlos hacia los requisitos reales.
Escríbelo al estilo "divulgación progresiva" (como SKILL.md)
Como vimos arriba, SKILL.md se carga bajo demanda; aplica la misma idea a AGENTS.md: divídelo en archivos pequeños y cárgalos de forma perezosa: "si haces A, lee el archivo X." Cuando no hace falta, el agente lo salta y no gasta contexto en ello.
En CLAUDE.md esto se hace con la sintaxis de import @path/to/file (verifica la sintaxis actual, porque las herramientas cambian rápido): el archivo raíz conserva solo el núcleo siempre cierto, mientras que los detalles de cada tipo de trabajo viven en archivos separados que se traen cuando son relevantes. Es el mismo mecanismo que usan las skills de Claude Code para cargar instrucciones según el contexto; para crear una, mira cómo crear una skill personalizada. Para el presupuesto general de contexto, mira cómo gestionar contexto y memoria.
¿Un archivo o dos? (el truco del symlink)
Si conservas un solo archivo, que sea AGENTS.md, ya que lo leen más herramientas. Si Claude Code es tu agente principal pero aun así quieres que toda herramienta funcione, un truco popular es tener una única fuente de verdad: escribe AGENTS.md y crea un symlink de CLAUDE.md hacia él.
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.mdAsí el contenido queda en un solo lugar y sirve a todas las herramientas. La contrapartida: pierdes la carga jerárquica y los imports de CLAUDE.md, así que, si dependes mucho de los imports @path, plantéate mantener CLAUDE.md como archivo real en vez de un symlink.
Antes/después: de un manual largo a ~una docena de líneas
Cualquiera que haya usado un kit de Claude Code desde los primeros días hasta ahora lo notará: de un CLAUDE.md largo, lo comprimí a apenas una docena de líneas. Porque este archivo debe ser específico del proyecto —con exactamente las reglas extra que este proyecto necesita— y no un cajón de sastre genérico que lo acumula todo.
La regla de la poda: cada línea debe responder "¿dónde cambia esto la decisión del agente?". Si no, es relleno de resumen: córtalo o empújalo a un archivo de carga perezosa. Una plantilla breve de CLAUDE.md para copiar está en la guía de CLAUDE.md.
Checklist de conservar / cortar
| ✅ Conservar | ❌ Cortar (o cargar bajo demanda) |
|---|---|
| Comandos de test / build / ejecución | Resumen del repositorio |
| Reglas que no se deben romper | Textos explicativos largos |
| Rutas / directorios importantes | Flujos poco usados |
Import @path al detalle cuando haga falta | Conocimiento general que el agente ya tiene |
Un kit con contexto breve de fábrica (AgentKit)
Si prefieres no ajustarlo tú misma, kits como AgentKit (agentkit.best, CLI ak, distinto de OpenAI AgentKit) traen una convención breve de CLAUDE.md más un conjunto de skills escritas al estilo de divulgación progresiva, así te saltas armar un manual inflado a mano. Para una visión general, lee la reseña de AgentKit o mira AgentKit (20% de descuento por el enlace).
Preguntas frecuentes (FAQ)
¿AGENTS.md y CLAUDE.md son lo mismo?
La misma idea, distinto nombre por herramienta. CLAUDE.md es la convención de Claude Code; AGENTS.md es el estándar multiherramienta que leen muchas herramientas (Codex, Copilot CLI, Gemini CLI, Cursor y Claude Code). CLAUDE.md aún conserva algunos extras, como la carga jerárquica y los imports.
¿Claude Code lee AGENTS.md?
Tal como están las cosas, Claude Code puede leer AGENTS.md junto con CLAUDE.md, pero esta área cambia rápido, así que verifica la documentación actual. Si dependes de los imports @path y de la carga jerárquica, CLAUDE.md sigue siendo el archivo raíz que conviene mantener.
¿De verdad los archivos de contexto ayudan a los agentes?
Según un estudio de 2026, no mejoran de forma fiable el éxito de las tareas (tanto los generados por LLM como los escritos por desarrolladores) y elevan el costo en más del 20%. Los resúmenes del repositorio en concreto no ayudaron, mientras que las instrucciones concretas sí se siguieron. Lección: conserva las instrucciones accionables y corta los resúmenes.
¿Cuán largo debe ser CLAUDE.md?
Lo más breve posible: conserva solo el núcleo siempre cierto y empuja el detalle a archivos de carga perezosa mediante imports @path. Cada línea debería cambiar la decisión del agente; si no, córtala.
¿Qué es la "divulgación progresiva" en CLAUDE.md?
Es dividir el contenido en archivos pequeños que se cargan bajo demanda: "si haces A, lee el archivo X." Cuando no es relevante, el agente lo salta y no gasta contexto en ello, igual que las skills cargan instrucciones cuando el contexto coincide.
¿Qué conservar y qué cortar en AGENTS.md?
Conservar: comandos de test/build/ejecución, reglas que no se deben romper, rutas importantes e imports al detalle cuando haga falta. Cortar: resúmenes del repositorio, textos largos, flujos poco usados y conocimiento general que el agente ya tiene.
¿En qué se diferencia SKILL.md de AGENTS.md?
SKILL.md es una capacidad reutilizable que se carga bajo demanda, solo cuando una tarea coincide con ella; AGENTS.md, en cambio, es contexto persistente siempre cargado. Para el recorrido completo de crear e instalar skills, mira cómo funcionan las Codex Skills.
Conclusión
Los archivos de contexto funcionan… cuando son breves y están escritos al estilo de divulgación progresiva. Escribirlos largos es sabotearte: más del 20% de costo sin mejor resultado. Corta los resúmenes, conserva las instrucciones accionables y carga el resto bajo demanda. Mira la guía de CLAUDE.md para una plantilla y, si además trabajas de forma autónoma, combínala con cómo usar el modo /goal con eficiencia.