Where Each Instruction Belongs: AGENTS.md, CLAUDE.md and SKILL.md

More than 4,300 engineers have upvoted a single GitHub issue requesting that Claude Code load AGENTS.md without help. In July 2026, on version 2.1.201, it still does not. Anthropic's own memory documentation now tells developers how to force the behavior anyway: run ln -s AGENTS.md CLAUDE.md in a terminal. In effect, the vendor ships a workaround for a file its own tool declines to read.

The argument is the less interesting part. The real engineering shows up in one line of the claude-api SKILL.md in Anthropic's public skills repository, in the description field of its YAML frontmatter. Unlike CLAUDE.md and AGENTS.md, that description decides whether Claude reads the remainder of the file at all. Three files and three loading models are involved, and the placement question answers itself once the gate is visible.

How the split came about

The timeline shows how the industry ended up here. In August 2025 the AGENTS.md specification launched as a universal set of instructions for AI coding assistants. Build commands, testing rules and project architecture could live in one place, and The idea was that Cursor, Copilot and standalone agents alike would pick up that one file.

In October 2025, two months on, Anthropic unveiled Agent Skills, which took a different approach to context. Rather than a flat markdown file of rules, a skill is a directory with its own metadata, scripts and reference documents.

Both formats had become open standards by December 2025. The skills spec was published at agentskills.io, while the AGENTS.md spec was handed to the Linux Foundation as an anchor project for the Agentic AI Foundation. Over 60,000 repositories and some two dozen tools now support AGENTS.md out of the box, so neither standard is going away.

The result is that teams now write the same instructions in three places: an AGENTS.md for the editor, a CLAUDE.md for the terminal and a SKILL.md for complicated workflows. Then they wonder why agents slow down and token bills climb. The cure starts with how these tools actually parse text.

The gate on a skill

A session does not begin with the agent reading every file in the project, since that would exhaust the context window and dilute the model's attention. It looks for particular entry points instead, and for skills that entry point follows a progressive disclosure model.

At startup the agent loads each installed skill's metadata into the system prompt. That metadata is a name and a description, costing about 100 tokens per skill. The agent then reads the user's request, weighs it against the loaded descriptions, and decides whether to open a skill's body. The description stands guard, with the reference material locked behind it.

Below is the frontmatter of the claude-api skill, as published in Anthropic's open repository.

---
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)

The description field does double duty. It tells the agent what the skill does, and it works as a programming interface through which the skill author encodes trigger logic.

TRIGGER and SKIP are conventions and not schema-defined fields. The author simply writes plain-English instructions about when the gate should open. The body of this skill runs to hundreds of lines of API reference. A question about a Postgres database fails the description check, and the reference text stays unloaded.

CLAUDE.md and AGENTS.md behave differently. They have no equivalent gate. Once an agent finds them on the path, it injects them at the start of the session, and they stay on for the entire conversation.

What belongs in which file

The loading model decides the contents. An injected file should hold only what the agent needs on every turn. A gated file should hold specialized knowledge that applies to particular tasks.

A repository called orchard shows how these files can coexist on disk without duplicating information.

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 holds the shared build rules, including style guidance, the monorepo layout, how to run tests and notes on dependencies. It is the baseline context any agent needs, whichever tool is reading. Its signature behavior is nearest-file-wins precedence: an agent working in services/payments/ reads the nested AGENTS.md first and prefers its local rules over the root ones. OpenAI manages its internal context with an 88-file monorepo pattern like this, and the nested files keep the window tight by loading only what the current directory needs.

CLAUDE.md has a narrower job. It holds directives that make sense only when the active agent is Claude Code.

Bloat is the common problem with CLAUDE.md files. Developers paste their entire AGENTS.md into CLAUDE.md, assuming Claude wants its own copy of the build rules. The right minimal form instead imports the shared standard into Claude's context.

# 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.
-->

A rule that applies across several tools belongs in AGENTS.md. The @AGENTS.md import is the main pattern recommended in Anthropic's memory documentation, while the symlink is the fallback for repositories with nothing Claude-specific to add that simply want the tool to read the standard file.

SKILL.md is the conditional capability layer, the place for recurring workflows, one-off capabilities and deep domain vocabulary. In orchard, .agents/skills/db-migration/ holds everything needed to run a Postgres migration safely, namely a Python script to check reversibility and a markdown note on Postgres lock modes. None of that belongs in AGENTS.md. An agent editing a CSS file in the UI package has no business receiving lock modes in its system prompt. The description gate ensures the skill loads only when a migration file is touched.

A routing rule

Once the loading models are clear, placing a new piece of context turns mechanical:

• Shared, tool-agnostic project context that every turn needs goes in AGENTS.md.
• Directives meant only for Claude Code go in CLAUDE.md, ideally as a short file that imports AGENTS.md.
• Situational workflows, scripts and domain references that only some tasks need go in a skill, behind a description that says when to open it.

Guarding the always-on budget

The difference between conditional and always-on loading is tied directly to agent performance.

A January 2026 study (arXiv:2601.20404) by researchers at King's College London, Singapore Management University, Heidelberg University and the University of Bamberg measured what AGENTS.md files actually do. Agent runtime dropped by 28.64% and output tokens by 16.58%, while tasks were completed at comparable rates. A shared instruction layer makes agents more efficient. They stop inventing build commands and running the wrong test suites, because the model reads the canonical rules once and gets on with the task.

That efficiency holds only while the context stays relevant. Every token placed in the system prompt draws on the model's attention. Suppose a team pastes a 500-word guide to database migrations into the root AGENTS.md. The agent then has to read it while fixing a frontend state bug, spending attention on Postgres lock modes when it should be thinking about React hooks.

Conditional loading protects the gains. Moving situational workflows into SKILL.md keeps the root AGENTS.md lean, which keeps the runtime gains of shared context and avoids paying attention costs for instructions that don't apply.

The bridge that exists and the one that does not

The ecosystem has a translation gap. Claude Code understands skills and their disclosure gates, but Cursor, Copilot and standalone CLI tools do not natively understand the .agents/skills/ layout.

A team that writes a database migration skill wants Cursor users to benefit from it as well. Hand-copying the skill into AGENTS.md would undo the single source of truth, so the answer is compilation.

Non-Claude agents can then see the skills without manual duplication. The generated block as it appears in orchard's AGENTS.md looks like this.

# 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

The bridge pulls out each skill's name, path and description. Non-Claude agents have no built-in progressive disclosure for these directories, so the summary in the skills block serves as their interface: a tool reading the AGENTS.md finds the block, reads the trigger conditions, and learns where on disk to look to carry out a migration.

The bridge that is still missing is Claude Code reading AGENTS.md natively, with no import or symlink. A prediction market on Manifold continues to trade on whether Anthropic will merge such support by the end of the year. The gap suggests that tool makers want to control their own context layer. Anthropic owns CLAUDE.md, and the community owns AGENTS.md. Cross-compatibility will keep depending on tooling and CI pipelines, not on specification mandates.

The system in the end

Looking over the orchard monorepo shows a setup that works. Nested AGENTS.md files hold the shared structural rules. A one-line CLAUDE.md handles the Claude-specific imports. The db-migration SKILL.md waits behind its description gate for a database task to trigger it, and the GitHub Action stitches everything together so that no developer writes the same rule twice.