AGENTS.md vs CLAUDE.md vs skills: which layer each instruction belongs in, and what to delete

Claude Code 2.1.277 began reading AGENTS.md on 18 September 2026, making five of the six major coding agents read that file without setup, though Claude Code still loads skills only from .claude/skills/ and not the shared .agents/skills/ folder. Vercel measured that an 8KB docs index placed in AGENTS.md passed 100% of its Next.js 16 API evals versus 53% with no docs, while the same docs delivered as a skill also scored 53% because the agent never called it in 56% of cases. Release 2.1.283 on 25 September added /doctor prompt-audit, which reads CLAUDE.md, AGENTS.md, rules and skills together and flags files that contradict each other.

AGENTS.md vs CLAUDE.md vs skills: which layer each instruction belongs in, and what to delete Put the facts every session needs in AGENTS.md https://stackness.dev/tools/agents-md , under 200 lines. Keep CLAUDE.md as an @AGENTS.md import plus anything only Claude Code https://stackness.dev/tools/claude-code needs. Move multi-step procedures into skills https://stackness.dev/tools/agent-skills , and move anything that must always happen into a hook or a permission rule. Since Claude Code 2.1.277 started reading AGENTS.md on 18 September 2026, five of the six major coding agents read that file without setup. Gemini CLI https://stackness.dev/tools/gemini-cli needs one setting. This post covers the evidence behind each layer, the skills folder the agents disagree on, and how often to delete things. For which file Claude Code loads when both exist, see the AGENTS.md vs CLAUDE.md post https://stackness.dev/blog/agents-md-vs-claude-md-which-file-claude-code-reads-and-the-flag-that-decided-it . What changed now that Claude Code reads AGENTS.md? Claude Code reads AGENTS.md when a project has no CLAUDE.md, .claude/CLAUDE.md or CLAUDE.local.md , and a /config setting can load both. Nothing about that has changed since 2.1.281 on 23 September. What did not change: Claude Code still reads skills only from .claude/skills/ , not the .agents/skills/ folder most other agents now share. One Hacker News https://news.ycombinator.com/item?id=49760187 comment on launch day: "Note that this does not include .agents/skills . Argh." The skills docs https://code.claude.com/docs/en/skills confirm it: the instruction file is now shared, but skills still need a Claude-specific folder. Release 2.1.283 on 25 September added /doctor prompt-audit , which reads CLAUDE.md, AGENTS.md, rules and skills together and flags files that contradict each other. What belongs in AGENTS.md and what belongs in a skill? AGENTS.md holds facts the model needs in every session and cannot work out from the code: commands it would not guess, conventions that differ from defaults, and gotchas. A skill holds procedures and reference material that matter sometimes, because only its name and description load until it is used. Rules that must hold every time belong in a hook or permission, since instruction text is a request, not a guarantee. Anthropic's features overview https://code.claude.com/docs/en/features-overview and memory docs https://code.claude.com/docs/en/memory give the split for Claude Code, and the other agents' docs describe the same layers under different names: | Layer | When it loads | What goes in it | |---|---|---| | AGENTS.md or CLAUDE.md | Every request, in full | Build and test commands, conventions, gotchas. Under 200 lines | | Path-scoped rules | When matching files open | "Migrations are append-only" for one folder | | Skill | Description always, body on use | Deploy steps, release checklists, API reference | | Hook | Never in context | "Never edit .env ", a formatter after every edit | | Settings and permissions | Enforced by the client | Blocked commands, sandbox | | MCP https://stackness.dev/tools/model-context-protocol server | Tool names, schemas on demand | Access to a database or a tracker | Custom slash commands are skills now: .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy . Anthropic's rule of thumb: a convention the model gets wrong twice goes in CLAUDE.md, a playbook you paste a third time becomes a skill, and anything you want "every time without asking" becomes a hook. The measured evidence supports the split, with caveats: - Always-loaded docs beat an uncalled skill. Vercel https://vercel.com/blog/agents-md-outperforms-skills-in-our-agent-evals put an 8KB docs index in AGENTS.md and passed 100% of its Next.js https://stackness.dev/tools/next-js 16 API evals, against 53% with no docs. The same docs as a skill also scored 53%, because in 56% of cases the agent never called it. One framework, one task type, and no model named. - General context files add cost more than accuracy. An ETH Zurich study https://arxiv.org/abs/2602.11988 found context files "do not generally improve task success rates" while raising inference cost by over 20%. Repository overviews were the least useful part. - Focused skills help, bulk skills hurt. SkillsBench https://arxiv.org/abs/2602.12670 measured curated skills adding 16.6 points on average. Force-injecting public web skills https://arxiv.org/abs/2608.23067 lowered pass rates by 1.3% to 4.2% and raised token cost by 72% to 394%. Always-loaded text pays when it carries something the model cannot find in the repository. A skill pays when it is narrow and gets invoked. Do CLAUDE.md and AGENTS.md conflict when both exist? Not by default, because Claude Code then reads only CLAUDE.md. With the claude-md-and-agents-md setting both load, CLAUDE.md first, and Anthropic documents no winner: if two rules contradict each other, "Claude may pick one arbitrarily". Other agents resolve conflicts differently, so a contradiction between the files produces different behaviour in each tool. | Agent | When instructions conflict | |---|---| | Claude Code | Load order only. The docs say Claude "uses judgment to reconcile them" | | OpenAI Codex https://stackness.dev/tools/codex-cli | Files closer to the working directory "override earlier guidance" | | GitHub Copilot https://stackness.dev/tools/github-copilot | A ranked list with AGENTS.md below repository instructions, but "all sets of relevant instructions are provided" | | Cursor https://stackness.dev/tools/cursor | Nested AGENTS.md files combine, "more specific instructions taking precedence" | A study of 100 popular repositories https://arxiv.org/abs/2606.15828 found conflicting instructions in 28% of their agent files. If you keep both files, run /doctor prompt-audit after editing either one. How do teams keep one handbook readable by six different agents? Make AGENTS.md the source. Add a CLAUDE.md whose first line is @AGENTS.md , with Claude-only notes below it. Set context.fileName for Gemini CLI. Keep skills in one canonical folder symlinked into each agent's path, and put MCP servers in a root .mcp.json . No single skills folder is read by all six agents, so the skills step is the one that needs tooling. | Agent | Reads AGENTS.md | Project skills folders | |---|---|---| | Claude Code | As a fallback, or both with a setting | .claude/skills/ | | OpenAI Codex | Yes, up to 32 KiB combined | .agents/skills/ | | Cursor | Yes | .agents/skills/ , .cursor/skills/ , .claude/skills/ | | GitHub Copilot | Yes, support varies by surface | .github/skills/ , .claude/skills/ , .agents/skills/ | | Gemini CLI | Only with context.fileName | .gemini/skills/ , .agents/skills/ | | Windsurf https://stackness.dev/tools/windsurf , now Devin Desktop | Yes | .devin/skills/ , .windsurf/skills/ , .agents/skills/ , .claude/skills/ if enabled | Sources: each vendor's documentation, checked on 29 September 2026. Three public repositories show the options in practice: - One file and a symlink. vibe-code-stack-for-ceos https://github.com/NoahDuongMaster/vibe-code-stack-for-ceos keeps a single 621-line AGENTS.md with CLAUDE.md as a symlink, and no nested files "to avoid drift". Anthropic warns that symlinks check out as plain text on Windows unless core.symlinks is on, so the import is safer. - The reverse pointer. Salesforce's agentforce-adlc https://github.com/SalesforceAIResearch/agentforce-adlc makes AGENTS.md a three-line pointer to a 202-line CLAUDE.md. A pointer only works if the agent decides to open the file. - One skills folder, many links. Vercel's npx skills https://github.com/vercel-labs/skills keeps one copy and symlinks it into .claude/skills/ , .agents/skills/ and the rest. Hooks, permission rules and subagents do not port. The Salesforce installer marks them "N/A" for Codex and Cursor. On Stackness, 11 real public profiles list a coding agent from the AI tools developers use https://stackness.dev/categories/ai-tools . Four of them list two or more agents, one of them mine, and one lists five, as of 29 September 2026 data sources https://stackness.dev/about/data-sources . The numbers are small, but that is who this section is for. How often should you audit your agent files, and what do you delete? Anthropic gives no calendar, only "prune it regularly". Addy Osmani https://addyo.substack.com/p/audit-your-agent-files runs Claude Code's /doctor "every few weeks", and Boris Cherny of the Claude Code team is reported https://dev.to/reporails/opus-5-delete-your-claudemd-9ga to say delete everything every six months. Between those, auditing monthly and after every model upgrade catches most drift. Delete what the model can infer from the code, and turn rules that must hold into tests, hooks or permissions. The repository study gives the delete list, measured on 100 popular repositories: | Smell | Share of files | What to do | |---|---|---| | Lint leakage: rules a linter or formatter already checks | 62% | Delete | | Context bloat: 200 or more lines | 42% | Trim or split into rules | | Skill leakage: rarely needed procedures | 35% | Move to a skill | | Conflicting instructions | 28% | Pick one | | Init fossilization: never edited after the first commit | 24% | Re-read it | | Blind references: paths with no reason given | 16% | Explain or delete | 91% of the files had at least one. Claude Code ships three tools for the job: /doctor trims content the model can derive from the codebase, /doctor prompt-audit flags stale paths, stale commands and contradictions, and /skill-doctor lists skills that have never been invoked. Osmani's rule for the rest: keep "things the model can't easily infer from the code", and "if a rule must always hold, encode it in a test, hook, or permission". Skills need the same pruning. One study https://arxiv.org/abs/2608.14036 found that as a skill pool grew from 5 to 100, the share of retrieved skills the agent used fell from 29.6% to 3.3%. The awesome-claude-skills https://github.com/ComposioHQ/awesome-claude-skills list has 75,842 stars and a README that says "1000+" skills. I counted 164 listed. As Osmani puts it, "Installing a useful skill and keeping it forever are separate decisions." Key numbers - 18 September 2026 : Claude Code 2.1.277 starts reading AGENTS.md when no CLAUDE.md exists changelog https://code.claude.com/docs/en/changelog . - 5 of 6 of the agents in this post read AGENTS.md without setup. Gemini CLI needs context.fileName . - 200 lines : Anthropic's target size for a CLAUDE.md file memory docs https://code.claude.com/docs/en/memory . - 100% vs 53% : Vercel's pass rate with an 8KB docs index in AGENTS.md against no docs, and 56% of cases where the equivalent skill was never called 27 January 2026 . - Over 20% : the added inference cost of context files in the ETH Zurich study, with no general gain in task success June 2026 , v2 . - 91% of 100 popular repositories' agent files had at least one configuration smell. 62% repeated linter rules arXiv 2606.15828 https://arxiv.org/abs/2606.15828 . - 4 of 11 real public Stackness profiles with a coding agent list two or more, as of 29 September 2026 . Quick answers AGENTS.md vs CLAUDE.md vs skills: what is the difference? AGENTS.md and CLAUDE.md load in full on every request and hold facts. A skill loads its name and description up front and its body only when used, so it holds procedures and reference material. AGENTS.md is read by most agents, CLAUDE.md only by Claude Code. Should I use AGENTS.md or CLAUDE.md? If more than one agent works in the repository, AGENTS.md, with a CLAUDE.md that imports it via @AGENTS.md . If only Claude Code does, either works. Do skills work outside Claude Code? Yes. Codex, Cursor, GitHub Copilot, Gemini CLI and Devin Desktop read SKILL.md folders, but not all from the same path. Claude Code reads only .claude/skills/ . Where do slash commands go now? In Claude Code, custom commands have been merged into skills. A file in .claude/commands/ still works, but a skill can carry supporting files. What should never go in AGENTS.md? Rules a linter already checks, facts the model can read from the code, and rules that must never be broken. The first belong in the linter, the second need no line at all, and the third belong in a hook or permission. How often should I audit my agent files? Monthly and after every model upgrade. Run /doctor prompt-audit in Claude Code and delete what the model does correctly without the line.