CLAUDE.md vs AGENTS.md vs SKILL.md: Which File Owns What in 2026

Three files, three loading models, one decision you make once.

Read the article for free **here**.

Over 4,300 engineers upvoted the same GitHub issue asking if Claude Code could please read AGENTS.md natively. As of Claude Code 2.1.201 in July 2026, the answer remains no.

Anthropic updated its own memory documentation to tell developers how to force the behavior anyway. The official command is ln -s AGENTS.md CLAUDE.md right in the terminal. Anthropic ships the workaround for the file its own tool refuses to read.

The engineering under this is more interesting than the argument. A single line inside the claude-api SKILL.md in Anthropic's public skills repository explains the situation. The answer lies in the description field of the YAML frontmatter. Unlike CLAUDE.md and AGENTS.md, that description is the reason Claude reads the rest of the file.

Three files, three loading models, and the decision only becomes obvious once you see the gate.

The Context Reshuffle of Late 2025

The timeline explains how the industry arrived at this split. In August 2025, the AGENTS.md specification launched to give AI coding assistants a universal set of instructions. A developer could define build commands, testing rules, and project architecture in one place. Cursor, Copilot, and independent agents would all read the same file.

Two months later in October 2025, Anthropic introduced Agent Skills. This presented a different approach to context. Instead of a flat markdown file full of rules, skills were packaged as directories with their own metadata, scripts, and reference documents.

By December 2025, both formats became open standards. The skills standard was published at agentskills.io. The AGENTS.md specification moved under the Linux Foundation to anchor the Agentic AI Foundation. More than 60,000 repositories and two dozen tools adopted AGENTS.md natively. Both standards found permanent footing.

Engineering teams now write the same instructions in three places. They create an AGENTS.md for their editor, a CLAUDE.md for their terminal, and a SKILL.md for their complex workflows. They wonder why their agents slow down and rack up token costs. The fix requires looking at how these tools parse text.

How SKILL.md Decides Whether It Gets Read

When a developer starts a new session, the agent does not read every file in the project. Doing so would exhaust the context window and dilute the model’s attention. The agent looks for specific entry points. For skills, the entry point relies on a progressive disclosure model.

At startup, the agent loads the metadata of every installed skill into its system prompt. This metadata consists of the name and the description, taking up about 100 tokens per skill. The agent reads the user’s prompt, evaluates the loaded descriptions, and decides if it needs to open the actual skill body.

The description acts as a gatekeeper. The reference material sits behind it.

Here is the YAML frontmatter from the claude-api SKILL.md in the public Anthropic 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 two jobs. It tells the agent what the skill does, and it serves as the programming interface for the skill author to encode trigger logic.

The words TRIGGER and SKIP are conventions rather than schema-defined fields. The author writes plain English instructions telling the agent when to open the gate. The body of this skill contains hundreds of lines of API reference material. If the user asks about a Postgres database, the description fails the check and the agent never loads the reference text.

CLAUDE.md and AGENTS.md operate differently. Those files have no equivalent gate. Once an agent discovers them on the path, it injects them at session start. They remain always-on.

What Each File Actually Owns

The loading model dictates what belongs in each file. An injected file should only contain information the agent needs for every turn of the conversation. A gated file should contain specialized knowledge that applies to specific tasks.

The orchard/ repository demonstrates how these files compose 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 handles the shared build rules. This file covers style guidelines, monorepo layout explanations, test invocations, and dependency notes. It holds the baseline context an agent needs regardless of which tool is reading it.

The defining feature of AGENTS.md is the nearest-file-wins precedence rule. When an agent works inside services/payments/, it reads the nested AGENTS.md first. It prioritizes those local rules over the root rules. OpenAI uses an 88-file monorepo pattern to manage its internal context this way. The nested files keep the context window tight by loading only the rules relevant to the current directory.

CLAUDE.md serves a narrower purpose. This file manages tool-specific directives that only make sense when the active agent is Claude Code.

Most CLAUDE.md files in the wild suffer from bloat. Developers copy their entire AGENTS.md into CLAUDE.md because they assume Claude needs its own copy of the build rules. The correct minimal form uses an import directive to pull 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.
-->

If a rule applies across multiple tools, it belongs in AGENTS.md. The @AGENTS.md syntax is the primary pattern recommended in the Anthropic memory documentation. The symlink is the fallback for repositories that have nothing Claude-specific to add and just want the tool to read the standard file.

SKILL.md operates as the conditional capability layer. This is where repeated workflows, one-shot capabilities, and deep domain vocabulary live.

In the orchard/ repository, the .agents/skills/db-migration/ directory holds everything needed to run a Postgres migration safely. It has a Python script to check reversibility and a markdown file explaining Postgres lock modes. None of this information belongs in AGENTS.md. If an agent updates a CSS file in the UI package, it should not have Postgres lock modes injected into its system prompt. The description gate ensures the skill only loads when the agent touches a migration file.

The Decision Table

Once the loading models are clear, deciding where to put a new piece of context becomes mechanical. Teams can use this mapping to route their instructions to the right layer.

Protecting the Always-On Context Budget

The distinction between conditional and always-on loading ties directly to agent performance.

In January 2026, researchers from King’s College London, Singapore Management University, Heidelberg University, and the University of Bamberg published a study (arXiv:2601.20404) analyzing the impact of AGENTS.md files. The findings showed that using AGENTS.md reduced agent runtime by 28.64% and decreased output tokens by 16.58%, while maintaining comparable task completion rates.

Providing a shared instruction layer makes agents more efficient. Agents stop hallucinating build commands and running the wrong test suites. The model reads the canonical rules once and executes the task.

That efficiency only holds if the context remains relevant to the current task.

Every token injected into the system prompt consumes the model’s attention mechanism. If a team dumps a 500-word database migration guide into the root AGENTS.md, the agent has to read it while fixing a frontend state bug. The model spends attention processing Postgres lock modes when it should be focusing on React hooks.

Conditional loading protects the efficiency gains of AGENTS.md. By moving situational workflows into SKILL.md, the root AGENTS.md stays lean. The agent gets the runtime benefits of shared context without the attention penalty of irrelevant instructions.

The Bridge That Exists, The Bridge That Doesn’t

The ecosystem faces a translation problem. Claude Code understands skills and their progressive disclosure gates. Other agents like Cursor, Copilot, and independent CLI tools do not natively understand the .agents/skills/ directory structure.

If a team writes a database migration skill, they want their Cursor users to benefit from it. Rewriting the skill manually into AGENTS.md defeats the purpose of maintaining a single source of truth. The solution is compilation.

The dave1010/skills-to-agents@v2 GitHub Action handles this translation. It runs in the CI pipeline, walks the .agents/skills/ directories, parses the YAML frontmatter of every SKILL.md, and emits a compiled block into the root AGENTS.md file.

This makes the skills visible to non-Claude agents without requiring manual duplication. Here is the generated block sitting inside the orchard/ repository's AGENTS.md file.

# 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 extracts the name, the path, and the description. Because non-Claude agents lack a native progressive disclosure mechanism for these directories, the summary inside the <skills> block becomes the interface. A tool reading this AGENTS.md sees the block, reads the trigger conditions, and knows where to look on disk to execute a migration.

The bridge that does not exist yet is Claude Code reading AGENTS.md natively without an @ import or a symlink. The prediction market on Manifold continues to trade on whether Anthropic will merge support by the end of the year.

The missing native bridge signals that tool makers want control over their context layer. Anthropic controls CLAUDE.md. The community controls AGENTS.md. Cross-compatibility will continue to rely on tooling and CI pipelines rather than specification mandates.

Closing

Looking back at the orchard/ monorepo reveals a system that works. The AGENTS.md files hold the shared structural rules. The one-line CLAUDE.md handles the tool-specific memory imports. The .agents/skills/db-migration/SKILL.md sits behind its description gate, waiting for a database task to trigger it. The GitHub Action stitches them together so no developer ever writes the same rule twice.

if this helped, clap 👏 so others can find it too — and if you want the shorter, sharper cuts of stuff like this, I also post notes on substack. Further reading:

***The 8 Skills Every Claude Code Setup Needs in 2026: ***Specific SKILL.md files worth installing after reading this piece.

**I Turned Claude Code Into My Chief of Staff (One Folder, 6 Skills): **One engineer’s actual six-skill setup running a full workflow.

**Inside Claude Code’s Leak: 8 Compaction Modes, 3 Memory Tiers, 44 Flags Anthropic Never Talked About: **CLAUDE.md memory tiers and flags Anthropic never documented publicly.

**I Spent 6 Months Tuning Claude Code. Here’s the Exact Setup That Finally Worked: **Production-grade Claude Code configuration from six months of iteration.

**Claude Code vs Cursor vs Devin vs Copilot in 2026: The Comparison Everyone Is Still Getting Wrong: **Where each coding agent lands beyond the benchmark marketing.