AGENTS.md vs CLAUDE.md vs skills: qué va dónde

AGENTS.md es un archivo markdown plano en la raíz de tu repositorio que le dice a los agentes de codificación cómo trabajar en tu proyecto: cómo construirlo, cómo ejecutar las pruebas, qué convenciones seguir, qué dejar en paz. Sin esquema, sin secciones obligatorias, sin registro. El estándar entero cabe en una frase: pon un archivo llamado AGENTS.md en tu repo, y los agentes que soporten la convención lo leerán antes de tocar tu código.

La gente lo llama el "README para agentes", y la analogía se sostiene. Un README le explica tu proyecto a humanos que acaban de llegar. AGENTS.md se lo explica a software que acaba de llegar. La diferencia es que el agente de verdad seguirá las instrucciones, así que las vagas cuestan dinero real en tokens desperdiciados y ediciones equivocadas.

Probamos herramientas de agentes para vivir en SkillProof, y hemos visto a este archivo pasar de ser un proyecto paralelo de OpenAI a lo más parecido a un estándar compartido que tiene la codificación agéntica. Este artículo cubre cómo se relaciona con CLAUDE.md y los otros dialectos de herramientas, y dónde encajan las skills, porque resuelven un problema distinto del que casi todo el mundo asume.

Qué es AGENTS.md, y quién lo lee de verdad

La convención salió del equipo de Codex de OpenAI a mediados de 2025 y rápidamente fue respaldada por Jules de Google, Cursor, Factory, Amp y otros. La propuesta era simple: cada proveedor de agentes había inventado su propio archivo de instrucciones, y las raíces de los repos se estaban llenando de markdown casi idéntico dirigido a robots distintos. AGENTS.md propuso un nombre de archivo que todos leyeran.

La adopción desde entonces ha sido real pero desigual. Aquí va el mapa honesto tal como lo vemos a mediados de 2026:

Herramienta	Lee AGENTS.md	Dialecto nativo
OpenAI Codex	Sí, nativo	Ninguno, AGENTS.md es el formato
GitHub Copilot (agente de codificación, VS Code)	Sí	.github/copilot-instructions.md
Cursor	Sí	.cursor/rules/*.mdc
Google Jules	Sí, nativo	Ninguno
Gemini CLI	Sí, vía config	GEMINI.md
Claude Code	No de forma nativa	CLAUDE.md
Zed	Sí	Ninguno
Amp	Sí	Ninguno
Aider	No	CONVENTIONS.md
Windsurf	No	.windsurf/rules/

Dos cosas destacan en esa tabla. Primero, la columna de respuestas "sí" es larga y sigue creciendo; cuando un agente nuevo se lanza en 2026, el soporte de AGENTS.md suele estar en las notas de lanzamiento. Segundo, los dialectos no han desaparecido. Copilot sigue leyendo su propio archivo de instrucciones, Cursor todavía tiene reglas con globs y modos de activación que AGENTS.md no puede expresar, y Claude Code, la herramienta con la que pasamos más tiempo, todavía quiere un CLAUDE.md.

Así que la situación práctica es esta: AGENTS.md es la lengua franca, los dialectos son donde vive el poder específico de cada herramienta, y cualquier equipo que ejecute más de un agente necesita una política para mantenerlos sincronizados. Esa política es la mayor parte de este artículo.

Lo que va en el archivo es menos discutido de lo que fue el nombre del archivo. Los AGENTS.md que funcionan cubren configuración y comandos de build, cómo ejecutar las pruebas, notas de estilo de código que el linter no puede detectar, y límites arquitectónicos ("la lógica de pagos vive en packages/billing, no la pongas en ningún otro sitio"). Los archivos que no funcionan se leen como declaraciones de misión. Un agente no necesita saber que valoras el código limpio. Necesita el comando que comprueba si el código está limpio.

AGENTS.md vs CLAUDE.md

Estos dos archivos hacen casi el mismo trabajo para lectores distintos. Ambos son archivos de instrucciones a nivel de proyecto. Ambos se cargan en el contexto al inicio de una sesión. Ambos deberían ser cortos, porque cada línea cuesta tokens en cada petición. Si ya has escrito un buen CLAUDE.md, ya sabes escribir un buen AGENTS.md, y nuestro consejo en buenas prácticas de CLAUDE.md se traslada casi línea por línea.

Las diferencias merecen conocerse antes de unificarlos:

Audiencia. CLAUDE.md lo lee exactamente una herramienta. Eso significa que puede referenciar con seguridad maquinaria específica de Claude: skills, hooks, subagentes, servidores MCP, ajustes de permisos. Un AGENTS.md que dice "usa la skill systematic-debugging antes de proponer un arreglo" es ruido para Codex y Copilot, que no tienen ni idea de qué es una skill.

Jerarquía e importaciones. Claude Code combina archivos CLAUDE.md de varios niveles (usuario global, raíz del proyecto, subdirectorios) y soporta importaciones @ruta/al/archivo dentro de ellos. AGENTS.md también soporta anidamiento, con el archivo más cercano teniendo prioridad, pero la sintaxis de importación es propia de Claude.

Cumplimiento. Ningún archivo se hace cumplir. Ambos son sugerencias para un modelo de lenguaje. Cualquier cosa que deba pasar siempre pertenece a un hook o a CI, no a ninguno de los dos archivos. Esto decepciona a la gente por igual en todas las herramientas.

Si tu equipo usa Claude Code junto con cualquier otra cosa, necesitas ambos archivos, y el modo de fallo es obvio: dos archivos que dicen casi lo mismo, desalineándose hasta que un agente sigue el que está desactualizado. Dos patrones lo evitan, y hemos probado ambos.

El symlink. Haz que AGENTS.md sea el archivo real y que CLAUDE.md apunte hacia él:

# AGENTS.md is the source of truth
ln -s AGENTS.md CLAUDE.md
git add AGENTS.md CLAUDE.md

Claude Code sigue el symlink y lee el contenido como si fuera su propio archivo. Esta es la opción de cero mantenimiento, y es la correcta cuando no tienes nada específico de Claude que decir. Su límite es la identidad exacta: ambos lectores reciben cada palabra, incluidas las que solo le importan al otro.

El envoltorio fino. Mantén AGENTS.md como la fuente compartida, y haz que CLAUDE.md sea un archivo pequeño que lo importa y añade líneas exclusivas de Claude:

# CLAUDE.md
@AGENTS.md

## Claude-specific
- Use the git-workflow skill for commits and PRs.
- Never edit files under infra/ without asking.

Esto es lo que ejecutamos en nuestros propios repos. Los hechos compartidos viven una vez, los extras de Claude viven donde solo Claude los verá, y un diff a AGENTS.md actualiza cada herramienta en el mismo momento. La misma forma funciona a la inversa para otros dialectos: mantén .github/copilot-instructions.md y los archivos de reglas de Cursor reducidos a unas pocas líneas que remitan a AGENTS.md para todo lo que ambas herramientas necesiten. Comparamos esos dialectos en detalle en skills de Claude vs reglas de Cursor y skills de Claude vs instrucciones de Copilot.

Una advertencia de nuestras pruebas: elijas el patrón que elijas, elige uno. Los repos que llevan un CLAUDE.md completo y un AGENTS.md completo con contenido editado de forma independiente son el escenario de desalineación con pasos extra.

AGENTS.md vs skills: capas completamente distintas

Esta es la comparación que la gente realmente busca, y es la que se construye sobre un error de categoría. AGENTS.md y las skills no son formatos que compitan. Se sitúan en capas distintas de la pila y responden preguntas diferentes.

AGENTS.md responde: ¿qué debería saber cualquier agente sobre este proyecto? Son hechos sobre un lugar. Viaja con el repositorio, se aplica a cualquier agente que aparezca, y no dice nada sobre cómo hace su trabajo el agente más allá de las reglas locales.

Una skill responde: ¿cómo debería este agente realizar este tipo de tarea? Es un comportamiento, empaquetado en una carpeta con un SKILL.md, cargado bajo demanda cuando la tarea coincide con su descripción. Viaja contigo, no con el repo. Instala una skill de depuración una vez y funciona en cada proyecto que abras, tenga o no ese proyecto algo que ver contigo antes. Cubrimos la mecánica en ¿Qué son las skills de Claude?, pero el modelo de carga es la diferencia clave: el contenido de AGENTS.md se queda en el contexto durante toda la sesión, mientras que una skill cuesta unos cien tokens de metadatos hasta el momento en que una tarea la activa.

Aquí está la pila completa tal como la dibujamos en las pizarras:

Capa	Vive en	Acotada a	Se carga	Pregunta que responde
AGENTS.md	Raíz del repo	El proyecto, cualquier agente	Cada sesión	¿Qué es este lugar?
Dialecto de herramienta (CLAUDE.md, reglas)	Repo o config de usuario	El proyecto, una herramienta	Cada sesión	¿Qué debería hacer esta herramienta aquí?
Skills	~/.claude/skills/ o .claude/skills/	Un agente, cualquier proyecto	Bajo demanda	¿Cómo se hace este tipo de tarea?
Servidores MCP	Config de herramienta	Una máquina o equipo	Definiciones de herramienta siempre en contexto	¿A qué puede llegar el agente?

Léela de arriba a abajo como capacidad que se ensancha y portabilidad que se estrecha. El archivo estándar es universal y tonto. El dialecto está atado a la herramienta y es algo más listo. Las skills son ricas en comportamiento pero por ahora atadas al agente. MCP es infraestructura viva con credenciales y procesos.

Un ejemplo concreto hace obvio el límite. "Ejecuta pnpm test --filter=changed antes de hacer commit" es una línea de AGENTS.md: es un hecho sobre tu repo, cierto para cualquier agente. "Al depurar, reproduce el fallo antes de proponer un arreglo, y nunca afirmes que un arreglo funciona sin volver a ejecutar la prueba que fallaba" es una skill, y de hecho es una que hemos probado y listado: systematic-debugging. No tiene nada que ver con ningún repo en particular. Ponerla en AGENTS.md significa copiarla en cada proyecto y pagar su coste en tokens en cada sesión, incluidas las sesiones donde nadie está depurando nada.

La regla general que les damos a los equipos: si copiarías una línea a un segundo repo sin cambios, no es contexto de proyecto, es comportamiento, y pertenece a una skill. Si una línea solo tiene sentido en este repo, es contexto, y pertenece a AGENTS.md.

La estrategia para equipos que ejecutan varias herramientas de IA

La mayoría de equipos con los que hablamos en 2026 no son talleres de un solo agente. Una mezcla típica es Claude Code para el trabajo pesado, Copilot en el editor, y Cursor en las máquinas de algunos rezagados. Aquí está la configuración que sobrevive al contacto con eso:

1. Escribe AGENTS.md como la fuente de verdad. Un archivo, en la raíz del repo, gestionado como código. Pon en él cada hecho que necesite cualquier agente: comandos, convenciones, límites, advertencias. Revisa los cambios en PRs, porque una instrucción equivocada aquí despista a cada agente que ejecute tu equipo.

2. Mantén los dialectos delgados. CLAUDE.md importa AGENTS.md y añade solo líneas específicas de Claude. Las instrucciones de Copilot y las reglas de Cursor reciben el mismo tratamiento: un puntero más lo que genuinamente no se pueda expresar en el archivo compartido. Nuestra prueba de "lo bastante delgado" es directa: si un archivo de dialecto supera una pantalla, algo en él probablemente pertenece a AGENTS.md o a una skill.

3. Pon el comportamiento reutilizable en skills. Disciplina de depuración, hábitos de commit y PR, estándares de escritura de pruebas, formato de documentos. Estos no pertenecen a ningún archivo por repo porque no son por repo. Instálalos una vez por agente y te siguen a todas partes. Nuestras elecciones probadas para trabajo de código están reunidas en las mejores skills de código, y git-workflow es la que instalaríamos primero en cualquier equipo al que le importe la higiene de commits.

4. Haz cumplir con hooks y CI, no con prosa. Cualquier cosa que deba pasar el 100% de las veces no puede vivir en un archivo markdown leído por un sistema probabilístico. Formatear al guardar es un hook. Las pruebas antes de fusionar son CI. Las capas de markdown son para el criterio, no para el cumplimiento.

Esta disposición tiene una propiedad que vale la pena nombrar: cada capa cambia a su propio ritmo. AGENTS.md cambia cuando cambia el proyecto, las skills cambian cuando cambia el oficio de tu equipo, y ningún agente lee nada dirigido a otro agente.

¿Ganará un solo estándar?

Nuestra opinión, con el sombrero de observador de estándares puesto: la capa de archivos convergerá, y la capa de comportamiento no.

La capa de archivos converge porque los incentivos apuntan todos en la misma dirección. Un archivo de contexto tiene poca superficie, los proveedores ganan compatibilidad por el coste de una comprobación de nombre de archivo, y los dueños de repos están visiblemente cansados de la proliferación de archivos de instrucciones. Esperamos soporte nativo de AGENTS.md en Claude Code eventualmente, porque la presión es pública y el coste de soportarlo es una búsqueda de archivo. Cuando eso pase, el patrón del symlink de arriba se vuelve un no-op que puedes borrar.

La capa de comportamiento es una historia distinta. Están apareciendo mecanismos parecidos a skills por todas partes: las skills de Claude, los modos de regla de Cursor, los archivos de prompt de Copilot, varias funciones de "playbook" en agentes más pequeños. Riman, pero cada uno codifica las ideas propias de su proveedor sobre activación y alcance. La descripción de activación y la carga progresiva de una skill se mapean sobre un glob de regla de Cursor más o menos como una sinfonía se mapea sobre un tono de llamada. La capa de comportamiento es donde los proveedores se diferencian, así que tienen todas las razones para seguir divergiendo.

Y aquí está la parte que los proveedores no ponen en sus notas de lanzamiento: la portabilidad de formato no es portabilidad de calidad. Un archivo de comportamiento sin probar falla de la misma manera en cada herramienta que lo carga. Se activa cuando no debería, o nunca se activa. Alrededor de la mitad de las skills comunitarias que sacamos de GitHub fallan nuestra primera pasada de pruebas, y las causas del fallo son independientes del formato: descripciones de activación vagas, e instrucciones que el autor nunca verificó contra una herramienta real. Escribimos el patrón en por qué la mitad de las skills de Claude no funcionan, y todo en ese artículo aplica a como sea que tu otro agente llame a su versión de las skills. Un estándar convergido nos daría un solo nombre de archivo y la misma vieja tasa de defectos.

Así que: estandariza tus hechos, porque el ecosistema se está estandarizando contigo. Luego sé exigente con tus comportamientos, porque nadie está estandarizando la calidad.

Preguntas frecuentes

¿Lee Claude Code el AGENTS.md?

No de forma nativa a mediados de 2026. Claude Code busca CLAUDE.md. Las soluciones estándar son un symlink (ln -s AGENTS.md CLAUDE.md) o un CLAUDE.md delgado que importa el archivo compartido con @AGENTS.md. Ambas funcionan; la versión de importación también te da un sitio para instrucciones exclusivas de Claude.

¿Debería AGENTS.md reemplazar mi CLAUDE.md?

Reemplaza su contenido, conserva el archivo. Mueve todo lo agnóstico de herramienta a AGENTS.md, luego reduce CLAUDE.md a una importación más líneas específicas de Claude sobre skills, hooks y permisos. Borrar CLAUDE.md directamente solo tiene sentido con el enfoque de symlink, donde los dos son literalmente los mismos bytes.

¿Puedo poner instrucciones tipo skill en AGENTS.md en vez de instalar skills?

Puedes, y para un repo pequeño y único está bien. Los costes aparecen a escala: las instrucciones se cargan en cada sesión sea o no relevante, y no te siguen a otros proyectos. Otros agentes que lean el archivo también reciben guía de comportamiento escrita para Claude. El comportamiento que reutilizarías entre repos pertenece a una skill.

¿Qué longitud debería tener un AGENTS.md?

Lo bastante corto como para que cada línea se gane su coste de contexto. La mayoría de los buenos que hemos revisado tienen entre 30 y 80 líneas. Si el tuyo tiene varios cientos, probablemente lleva contenido de comportamiento que pertenece a skills, o material de referencia que debería ser un documento enlazado que el agente lea bajo demanda.

¿Funcionan los archivos AGENTS.md en subdirectorios?

Sí, la convención soporta anidamiento: el archivo más cercano al código que se edita gana para esa zona. Los monorepos usan esto para darle a cada paquete sus propios comandos de build y pruebas. Mantén el archivo raíz para hechos de todo el repo y empuja los detalles específicos de paquete hacia abajo. Claude Code aplica la misma lógica de archivo más cercano a CLAUDE.md, así que el patrón de envoltorio también anida limpiamente.