A dónde pertenece cada instrucción: AGENTS.md, CLAUDE.md y SKILL.md

Más de 4,300 ingenieros han votado a favor de un único problema en GitHub en el que se solicita que Claude Code cargue AGENTS.md sin ayuda. En julio de 2026, en la versión 2.1.201, aún no lo hace. La propia documentación de memoria de Anthropic ahora indica a los desarrolladores cómo forzar este comportamiento: ejecutar ln -s AGENTS.md CLAUDE.md en una terminal. En efecto, el proveedor incluye una solución temporal para un archivo que su propia herramienta se niega a leer.

El argumento es la parte menos interesante. La verdadera ingeniería se encuentra en una línea del claude-api SKILL.md en el repositorio público de habilidades de Anthropic, en el campo de descripción de su frontmatter YAML. A diferencia de CLAUDE.md y AGENTS.md, esa descripción determina si Claude lee el resto del archivo o no. Están involucrados tres archivos y tres modelos de carga, y la cuestión de la ubicación se resuelve por sí sola una vez que se ve la condición de acceso.

Cómo surgió la división

La línea de tiempo muestra cómo llegó la industria a esta situación. En agosto de 2025 se lanzó la especificación AGENTS.md como un conjunto universal de instrucciones para asistentes de programación basados en IA. Las órdenes de construcción, las reglas de prueba y la arquitectura del proyecto podían estar en un solo lugar, con la idea de que herramientas como Cursor, Copilot y agentes independientes pudieran acceder a ese mismo archivo.

En octubre de 2025, dos meses después, Anthropic presentó Agent Skills, que adoptó un enfoque diferente al manejo del contexto. En lugar de un archivo plano en formato markdown con reglas, una habilidad es un directorio que contiene sus propios metadatos, scripts y documentos de referencia.

Hasta diciembre de 2025, ambos formatos se habían convertido en estándares abiertos. La especificación de habilidades se publicó en agentskills.io, mientras que la especificación AGENTS.md fue entregada a Linux Foundation como proyecto piloto para la Agentic AI Foundation. Actualmente, más de 60,000 repositorios y unas veinticuatro herramientas admiten AGENTS.md de forma predeterminada, por lo que ninguno de estos estándares desaparecerá.

El resultado es que ahora los equipos escriben las mismas instrucciones en tres lugares: un AGENTS.md para el editor, un CLAUDE.md para la terminal y un SKILL.md para flujos de trabajo complejos. Luego se preguntan por qué los agentes ralentizan su funcionamiento y los costos por tokens aumentan. La solución comienza con la forma en que estas herramientas interpretan realmente el texto.

La barrera de una habilidad

Una sesión no comienza con que el agente lea cada archivo del proyecto, ya que eso agotaría la ventana de contexto y diluiría la atención del modelo. En su lugar, busca puntos de entrada específicos y habilidades que sigan un modelo de revelación progresiva a partir de esos puntos de entrada.

Al iniciar, el agente carga los metadatos de cada habilidad instalada en la instrucción del sistema. Dichos metadatos incluyen un nombre y una descripción, lo que representa unos 100 tokens por habilidad. Luego el agente lee la solicitud del usuario, la compara con las descripciones cargadas y decide si debe mostrar el contenido de una habilidad. La descripción actúa como barrera, con el material de referencia guardado detrás de ella.

A continuación se muestra el frontmatter de la habilidad claude-api, tal como fue publicado en el repositorio abierto de Anthropic.

---
name: claude-api
description: |
  Reference for the Claude API / Anthropic SDK — model ids, pricing, params,
  streaming, tool use, MCP, agents, caching, token counting, model migration.
  TRIGGER — read BEFORE opening the target file; don't skip because it "looks
  like a one-liner" — whenever: the prompt names Claude/Anthropic in any form
  (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`,
  `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/
  model choice/limits/caching) — never answer from memory; OR the task is
  LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/
  RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/
  converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens).
  SKIP only when another provider is being worked on (overrides all triggers):
  OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR
  `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|
  cohere|ollama'` over the project hits (run this grep FIRST if no provider
  named — don't Read the file).
license: Complete terms in LICENSE.txt
---

# Claude API reference

Model IDs, pricing, request/response shapes, tool use, MCP, caching,
streaming, and migration notes for the Anthropic SDK.

... (body continues; only loaded if the description above passes the gate)

El campo de descripción cumple una doble función: indica al agente qué hace la habilidad y funciona como una interfaz de programación a través de la cual el autor de la habilidad codifica la lógica de activación.

TRIGGER y SKIP son convenciones y no campos definidos en el esquema. El autor simplemente escribe instrucciones en inglés sencillo sobre cuándo debe activarse la función. El cuerpo de esta habilidad consta de cientos de líneas de referencia a la API. Una pregunta relacionada con una base de datos Postgres falla en la verificación de la descripción, y el texto de referencia no se carga.

CLAUDE.md y AGENTS.md se comportan de manera diferente. No tienen un equivalente a esa función de activación. Una vez que un agente los encuentra en el camino, los inserta al inicio de la sesión y permanecen activos durante toda la conversación.

¿Qué pertenece a qué archivo?

El modelo de carga determina el contenido. Un archivo inyectado debe contener únicamente lo que el agente necesita en cada turno. Un archivo protegido debe albergar conocimientos especializados aplicables a tareas específicas.

Un repositorio llamado orchard muestra cómo estos archivos pueden coexistir en el disco sin duplicar información.

orchard/
├── AGENTS.md                          # root: shared, tool-agnostic project context
├── CLAUDE.md                          # 6 lines: imports + Claude-specific memory tiers
├── README.md                          # for humans
├── .github/
│   └── workflows/
│       └── skills-to-agents.yml       # dave1010/skills-to-agents@v2 → emits <skills> block into AGENTS.md
├── .agents/
│   └── skills/
│       └── db-migration/
│           ├── SKILL.md               # YAML frontmatter + body; loads only when description gate matches
│           ├── scripts/
│           │   └── check_reversibility.py
│           └── references/
│               └── postgres-lock-modes.md
├── services/
│   └── payments/
│       └── AGENTS.md                  # nested: subproject-specific rules; nearest-file-wins
└── packages/
    └── ui/

AGENTS.md contiene las reglas comunes de compilación, incluyendo orientaciones sobre estilo, la estructura del monorepo, cómo ejecutar pruebas y notas sobre dependencias. Es el contexto de referencia que cualquier agente necesita, independientemente de la herramienta que lo lea. Su comportamiento característico es dar prioridad al archivo más cercano: un agente que trabaja en services/payments/ lee primero el AGENTS.md anidado y prefiere sus reglas locales a las del nivel raíz. OpenAI gestiona su contexto interno con un patrón de monorepo formado por 88 archivos de esta manera, y los archivos anidados mantienen el espacio de trabajo reducido al cargar solo lo que necesita el directorio actual.

CLAUDE.md tiene una función más limitada. Contiene directivas que solo tienen sentido cuando el agente activo es Claude Code.

La sobrecarga es el problema común en los archivos CLAUDE.md. Los desarrolladores pegan todo su AGENTS.md en CLAUDE.md, asumiendo que Claude necesita su propia copia de las reglas de compilación. En cambio, la forma mínima adecuada importa el estándar compartido al contexto de Claude.

# Project instructions for Claude Code

@AGENTS.md

## Claude-specific

- Prefer `Explore` subagent for cross-file searches over 3 files; single grep otherwise.
- User-level memory lives at ~/.claude/CLAUDE.md — do not duplicate its rules here.

<!--
Alternative if you do not want an @ import and prefer one file on disk:

    ln -s AGENTS.md CLAUDE.md

This is Anthropic's own recommendation for repos that keep AGENTS.md canonical
and have nothing Claude-specific to add. See docs.claude.com/en/docs/claude-code/memory.
-->

Una regla que se aplica en varios herramientas debe encontrarse en AGENTS.md. La importación desde @AGENTS.md es el patrón principal recomendado en la documentación de memoria de Anthropic, mientras que el enlace simbólico sirve como solución alternativa para repositorios que no tienen nada específico de Claude que añadir y simplemente desean que la herramienta lea el archivo estándar.

SKILL.md es la capa de capacidades condicionales, el lugar adecuado para flujos de trabajo recurrentes, capacidades puntuales y vocabularios especializados en un dominio concreto. En orchard, la carpeta .agents/skills/db-migration/ contiene todo lo necesario para realizar una migración a Postgres de forma segura, es decir, un script en Python para verificar la reversibilidad y una nota en formato markdown sobre los modos de bloqueo de Postgres. Nada de esto pertenece a AGENTS.md. Un agente que edita un archivo CSS en el paquete de interfaz de usuario no debería recibir información sobre modos de bloqueo en su prompt del sistema. La regla de descripción asegura que la habilidad solo se cargue cuando se modifique un archivo de migración.

Una regla de enrutamiento

Una vez que los modelos de carga están listos, agregar un nuevo contexto se vuelve mecánico:

• El contexto del proyecto compartido e independiente de la herramienta que se necesita en cada turno debe ir en AGENTS.md.
• Las directivas destinadas únicamente a Claude Code deben ir en CLAUDE.md, idealmente como un archivo breve que importe AGENTS.md.
• Los flujos de trabajo situacionales, scripts y referencias de dominio que solo son necesarios para algunas tareas deben ir en una habilidad, detrás de una descripción que indique cuándo abrirla.

Proteger el presupuesto siempre activo

La diferencia entre la carga condicional y la siempre activa está directamente relacionada con el rendimiento del agente.

Un estudio de enero de 2026 (arXiv:2601.20404) realizado por investigadores del King’s College London, la Singapore Management University, la Universidad de Heidelberg y la Universidad de Bamberg midió qué es lo que realmente hacen los archivos AGENTS.md. El tiempo de ejecución de los agentes disminuyó un 28,64% y la cantidad de tokens generados, un 16,58%, mientras que las tareas se completaban a tasas comparables. Una capa de instrucciones compartida hace que los agentes sean más eficientes; dejan de inventar comandos de construcción y de ejecutar conjuntos de pruebas incorrectos, ya que el modelo lee las reglas canónicas una sola vez y procede con la tarea.

Esa eficiencia solo se mantiene mientras el contexto sigue siendo relevante. Cada token incluido en la instrucción del sistema consume la atención del modelo. Supongamos que un equipo pega una guía de 500 palabras sobre migraciones a bases de datos en el archivo AGENTS.md raíz. El agente entonces debe leerla mientras corrige un error en el estado del frontend, dedicando su atención a los modos de bloqueo de Postgres cuando debería concentrarse en los hooks de React.

La carga condicional protege estos beneficios. Al mover los flujos de trabajo específicos a SKILL.md, se mantiene ligero el archivo AGENTS.md raíz, lo que preserva las ventajas derivadas del contexto compartido y evita gastar atención en instrucciones que no son aplicables.

El puente que existe y el que no

El ecosistema presenta una brecha de traducción. Claude Code comprende las habilidades y sus mecanismos de revelación, pero Cursor, Copilot y las herramientas CLI independientes no entienden de forma nativa la estructura .agents/skills/.

Un equipo que desarrolla una habilidad para la migración de bases de datos desea que los usuarios de Cursor también se beneficien de ella. Copiar manualmente dicha habilidad a AGENTS.md anularía la fuente única de verdad, por lo que la solución es la compilación.

Los agentes que no son Claude podrán entonces ver las habilidades sin necesidad de duplicación manual. El bloque generado, tal como aparece en AGENTS.md de Orchard, se ve así.

# Project agents

Build with `pnpm build`. Test with `pnpm test`. Migrations under
`services/payments/migrations/` must run through the db-migration skill.

## Style

- TypeScript 5.x, strict mode on. No `any` in new code.
- Errors surface as structured `AppError` with a `code` field, never raw strings.

<!-- BEGIN skills-to-agents (auto-generated; edit .agents/skills/*/SKILL.md) -->
<skills>
  <skill name="db-migration" path=".agents/skills/db-migration/">
    Run a Postgres migration end-to-end. TRIGGER whenever the user asks to
    add/modify a migration, backfill a column, or lock-analyze a schema
    change. SKIP if the query is purely a read-only SELECT / EXPLAIN.
  </skill>
  <skill name="release-notes" path=".agents/skills/release-notes/">
    Draft the release notes for a merged PR. TRIGGER on "cut a release",
    "write release notes", or "prep the changelog". SKIP if the PR is a
    dependency bump.
  </skill>
</skills>
<!-- END skills-to-agents -->

## Repo layout

- `services/` — deployable services, each with its own AGENTS.md
- `packages/` — shared libraries
- `.agents/skills/` — Conditional workflows

El puente muestra el nombre, la ruta y la descripción de cada habilidad. Los agentes que no son Claude no cuentan con una funcionalidad integrada de revelación progresiva para estos directorios, por lo que el resumen en el bloque de habilidades sirve como su interfaz: una herramienta que lee AGENTS.md encuentra dicho bloque, lee las condiciones de activación y determina dónde buscar en el disco para realizar la migración.

El puente que aún falta es que Claude Code lea AGENTS.md de forma nativa, sin necesidad de importar o crear enlaces simbólicos. Un mercado de predicciones en Manifold sigue operando con apuestas sobre si Anthropic integrará dicho soporte para fin de año. Esta brecha indica que los creadores de herramientas desean controlar su propio nivel de contexto. Anthropic es dueño de CLAUDE.md, mientras que la comunidad posee AGENTS.md. La compatibilidad cruzada seguirá dependiendo de las herramientas y los pipelines de integración continua, no de requisitos impuestos por especificaciones.

El sistema al final

Al examinar el monorepo del huerto, se observa una configuración que funciona bien. Los archivos AGENTS.md anidados contienen las reglas estructurales compartidas. Un CLAUDE.md de una sola línea se encarga de las importaciones específicas para Claude. El SKILL.md de migración de bases de datos espera detrás de su puerta de descripción a que una tarea de base de datos lo active, y GitHub Action une todo para que ningún desarrollador escriba la misma regla dos veces.