The standing-instructions debate has been about file names for a year, and the file name is the least consequential thing on the table. What actually separates AGENTS.md, CLAUDE.md, Cursor's .mdc rules and Agent Skills is when their text enters the context window — on every turn, when a path matches, when the model decides it needs it, or only when a human types its name — and who is allowed to put text there in the first place. Sort them that way and two things happen: the portability argument collapses into a symlink, and the decision you were not making becomes obvious, which is how much of your guidance belongs anywhere other than the always-on rung.
At a glance
Four formats, one question each: who reads it, and what makes it load?
| Format | Read by | Loads when | Scope it lives in |
|---|---|---|---|
AGENTS.md |
~30 harnesses; governed by the Agentic AI Foundation | Always, every turn | Repository, nested per directory |
CLAUDE.md |
Claude Code | Always, every turn | Repository, user and enterprise layers |
.cursor/rules/*.mdc |
Cursor | Declarable: always, glob, model-requested or manual | Repository and user |
SKILL.md bundles |
Claude Code, Cursor, Codex, Gemini CLI, Antigravity | Name and description always; body on request | Repository, user, marketplace |
Why activation is the whole decision
Always-on text is a tax with compound interest
An always-loaded instruction file is prepended to every request for the life of the project. A 3,000-token house-style document is 3,000 tokens the model reads before it reads your question, on every turn of a forty-turn session, and the cost is not only the bill. Long context degrades selectively: instructions in the middle of a large preamble are followed less reliably than the same instructions in a short one, so the team that documented everything gets worse compliance than the team that documented five things. That is the counterintuitive result worth internalising — past some length, adding a rule reduces adherence to the rules already there. The mechanics are in effective vs advertised context.
On-demand text turns compliance into a retrieval problem
Move the same document behind a description the model matches against, and the cost drops to a sentence — but you have just acquired a new failure mode that produces no error. A skill that never triggers looks exactly like a skill that has no effect, and the only part of it that is always in context is the description, which means the description is the entire interface and the only thing you can debug. Teams routinely write a superb 400-line skill body and a vague one-line description, then conclude that skills do not work.
The asymmetry to hold on to: an always-on rule fails loudly — you see the agent following an outdated instruction — while an on-demand rule fails silently, by simply not arriving. That is why the right migration order is to move the biggest, least universal documents down a rung first, and to keep the short, genuinely universal constraints exactly where they are.
AGENTS.md — the portable one, and the one that settled
What it is
A plain Markdown file at the repository root, with no schema: build commands, test commands, conventions, the things a new contributor would ask. It is read natively by Codex, Cursor, Copilot, Gemini CLI, Aider, Windsurf, Zed, Jules and roughly twenty others, sits in more than 60,000 repositories, and its governance moved to the Agentic AI Foundation under the Linux Foundation alongside MCP and goose. Nesting works the way a developer expects: a file in a subdirectory applies to work under it.
What it is not
It is not an activation mechanism. There is no front-matter, no conditional loading, no scoping beyond the directory tree — which is exactly why it ported so easily to thirty tools, and exactly why it cannot express "only when touching the migrations". One file, always on, per directory. Its win is real and its ceiling is low, and both follow from the same design choice.
Who it fits
Every repository, as the short universal layer. If your AGENTS.md is longer than a page you have almost certainly put something in it that belongs a rung down.
CLAUDE.md — the same rung, with a fallback as of September
What it is
Claude Code's own instruction file, with a layering model AGENTS.md lacks: enterprise-managed, user-level and project-level files merge, so an organisation can push guidance that a repository cannot overwrite. That layering, not the name, is the substantive difference.
The convergence
Claude Code 2.1.277 added native AGENTS.md support, shipped as a built-in mod, and by 2.1.278 on 19 September 2026 the behaviour was settled: if no CLAUDE.md is present, Claude Code reads AGENTS.md instead. CLAUDE.md still takes precedence where both exist, and configuration can load both. This is the part of the argument that is now over — the long-running request for dual reads landed, and the remaining difference between the two files is the layering and the precedence order, not portability.
Who it fits
Keep CLAUDE.md when you need the enterprise or user layer, or Claude-specific guidance that would confuse another tool. Otherwise write AGENTS.md and let the fallback do the work, which beats both the symlink and the two-file sync scripts people have been maintaining.
Cursor rules — the only place activation is declarable
What it is
.cursor/rules/*.mdc files with three front-matter fields — description, globs, alwaysApply — that combine into four activation modes: Always Apply for universal constraints, Auto Attached when a glob matches the files in play, Agent Requested where the model reads the description and decides, and Manual where it loads only on an @rule-name mention. The legacy single .cursorrules file is functionally superseded by the directory.
Why this matters more than the vendor lock
No other format lets you say which rung a file sits on. That makes Cursor rules the best available thinking tool for this problem even if you never ship one: go through your own always-on file, and for each paragraph ask which of those four modes it should be in. In practice a page of universal constraints, three or four glob-scoped convention files and one or two manual references is where most repositories land — and discovering that is the value, because the same partition is implementable elsewhere with skills and directory nesting.
Who it fits
Cursor-first teams, and anyone auditing what their instruction file is actually asking for. The cost is that none of it ports: these files are read by one tool, so a mixed-tool team maintains them in addition to AGENTS.md rather than instead of it.
Agent Skills — the on-demand rung, and a different kind of artefact
What it is
A folder containing SKILL.md plus optional scripts, templates and reference files, loaded by progressive disclosure: the harness keeps the name and description in context and pulls the body only when the task matches. Introduced by Anthropic in October 2025, the format is now read by Claude Code, Cursor — which added Agent Skills in 2.4, reading .cursor/skills/ and, for compatibility, .claude/skills/ and .codex/skills/ — as well as Codex, Gemini CLI and Antigravity. It is the second cross-vendor convention after AGENTS.md itself to actually take hold.
Skills are verbs; the rest are adjectives
The distinction that keeps the comparison honest: AGENTS.md and rules describe what your project is, and a skill describes something the agent can do — with executable scripts and reference material attached, which no instruction file has. That also makes a skill a supply-chain artefact rather than a document: it can carry code, it arrives from marketplaces, and it is code regardless of being Markdown, per agent skills.
Who it fits
Any procedure longer than a paragraph that applies to a minority of sessions: release runbooks, a migration recipe, the eight steps of your deployment. Write the description as a retrieval key, not as a title — "use when writing or modifying database migrations in this repo" beats "Migrations guide" by a wide margin, and that sentence is the only part you get to debug.
The axes that actually separate them
The second axis is the one nobody puts in a comparison table and the one a security reviewer will ask about first. Every repository-scoped format on this page is attacker-controlled the moment you check out somebody else's branch: a fork's AGENTS.md, a PR branch's .mdc rules, a vendored skill bundle. These files are loaded before your first message and they are, functionally, a system prompt supplied by whoever opened the pull request. Reviewing a diff that touches an instruction file deserves the attention you give a change to CI, and running an agent on an untrusted branch deserves the attention you give to running its code — the same confusion of tiers described in context taint tracking.
The third axis explains why teams that "tried skills and went back to one big file" usually made the right call for the wrong reason. Always-on guidance is easy to debug because you can see it in every transcript; on-demand guidance requires you to log which files loaded per session before you can reason about it at all. If your harness does not tell you that, the honest choice is to stay on the always-on rung until it does.
When to pick which
| You want to… | Use | Because |
|---|---|---|
| State build, test and convention basics once, for every tool | AGENTS.md | Thirty harnesses read it, including Claude Code by fallback |
| Push guidance your repositories cannot override | CLAUDE.md enterprise layer | It is the only format here with a managed tier |
| Apply conventions only to certain file types | Cursor rule with globs | Path matching keeps it out of unrelated sessions |
| Ship a long procedure used in a minority of tasks | Skill bundle | Progressive disclosure keeps the body out of the base cost |
| Attach scripts or templates to a procedure | Skill bundle | No instruction file can carry executables |
| Stop your agent following instructions from a fork | User-scope files plus review | Repository-scope files are untrusted input |
FAQ
Does Claude Code read AGENTS.md now?
Yes, with a condition: from Claude Code 2.1.277, settled by 2.1.278 on 19 September 2026, it reads AGENTS.md when no CLAUDE.md is present. Where both exist CLAUDE.md wins by default, and configuration can load both — so the symlink workarounds are no longer necessary for the common case.
Should I delete CLAUDE.md and keep only AGENTS.md?
In a single-repository project with no managed policy, yes — one file read by everything beats two files kept in sync. Keep CLAUDE.md if you rely on the enterprise or user layer, or if you have Claude-specific instructions that would mislead other tools.
How long should an always-on instruction file be?
Short enough that you can name everything in it from memory. Under a page is a good target; the practical signal is that when you add a rule and adherence to existing rules drops, you are past the useful length and the next addition belongs in a skill or a glob-scoped rule.
Are skills replacing rules and instruction files?
No — they occupy a different rung. You still need always-on text for the constraints that apply to every task, because a rule that must always hold cannot depend on being retrieved. Skills replace the parts of a large instruction file that only matter sometimes.
What is the security exposure of these files?
They are loaded before your first message, so on an untrusted branch they act as an attacker-supplied system prompt, and a skill bundle can additionally carry executable scripts. Treat instruction-file diffs as code review, and treat starting an agent in a freshly cloned untrusted repository as running that repository.
Further reading
On this wiki:
- Agent skills — the on-demand packaging model and why it is code.
- Context engineering — budgeting what goes into the window before the task does.
- Long context: effective vs advertised — why more instructions can mean less adherence.
- The agent harness — the layer all four of these formats configure.
- Lifecycle hooks and harness config — the other configuration surface in the same bundles, with shell privileges.