CLAUDE.md vs AGENTS.md vs SKILL.md is not a fight over which standard wins — it is a question of how each file is loaded into the agent's context, and that loading model is what decides where a given instruction belongs.
It is a decision you make once. CLAUDE.md and AGENTS.md provide "always-on" injected context —
concatenated into the system prompt at the start of every session — while SKILL.md uses a gated
"progressive disclosure" model that only opens when its description matches the task in front of
you.
Use AGENTS.md as the universal standard every tool reads, CLAUDE.md as the Claude-Code-specific layer, and SKILL.md as the packaged unit for complex, conditional workflows (procedural memory). Put an instruction in the wrong file and you do not just pay in tokens — you dilute the model's attention and invite reasoning noise between sessions.
Three files, three context-loading models
The current split was forged during the "context reshuffle" of late 2025. In August 2025, the
AGENTS.md specification launched as a tool-agnostic "README for agents" — one place to define build
commands, testing rules, and architecture that Cursor, Copilot, and independent agents could all read.
Two months later, in October 2025, Anthropic introduced Agent Skills, shifting from a flat instruction
file to modular directories with their own metadata, scripts, and reference documents. By December
2025 both formats had become open standards: the skills standard was published at agentskills.io, and
AGENTS.md moved under the Linux Foundation to anchor the Agentic AI Foundation.
That history created a technical split: injected context (always-on) versus gated context
(just-in-time). Injected files like CLAUDE.md and AGENTS.md are automatically concatenated into the
system prompt at the start of every session. They are foundational, but they carry a fixed operational
overhead on every turn. Gated context stays dormant until a user's intent matches a skill's metadata, at
which point the full instructions are loaded. More than 60,000 repositories now manage tiered standards
this way.
Without these files, an agent is a fresh hire every time you press Enter. They provide a machine-readable map that stops the agent from hallucinating library usage or running the wrong test runner. But dumping everything into a single always-on file triggers "context saturation," where the agent spends attention complying with a wall of instructions instead of resolving the actual bug.
One gap still stands: as of today, Claude Code does not read AGENTS.md natively,
despite more than 4,300 engineers requesting it. Anthropic's own documentation ships the workaround — a
symlink that keeps a single source of truth without duplicating content:
ln -s AGENTS.md CLAUDE.md