CLAUDE.md vs AGENTS.md vs SKILL.md: what goes where

Short answer: AGENTS.md and CLAUDE.md hold the facts an agent needs in every session. SKILL.md holds one procedure the agent loads only when the task calls for it. AGENTS.md is the shared, tool-neutral file. CLAUDE.md is the Claude Code version of the same idea. They are not rivals, and most repos end up with more than one.

How we checked: loading rules and file locations come from the official docs for Claude Code memory, Claude Code skills, Codex AGENTS.md, agents.md and the Agent Skills specification, all read on November 9, 2026. We didn't benchmark any agent's adherence. Disclosure: we build Skillpack, which manages SKILL.md packages. It does not manage AGENTS.md or CLAUDE.md, so this isn't a ranking and none of the three files is "ours".

The three files at a glance

What AGENTS.md is

agents.md describes it as "a README for agents": a predictable place for the context a coding agent needs and a human contributor doesn't, such as build steps, test commands and conventions. There are no required fields. The FAQ says it's just standard Markdown and you can use any headings you like.

Two behaviors matter in practice:

• The closest file wins. In a monorepo you can place another AGENTS.md in each package. Agents read the nearest one in the directory tree, and explicit chat prompts override everything (agents.md).
• Codex builds a chain. It reads a global file from ~/.codex, then walks from the project root down to your working directory, at most one file per directory, and stops adding files at project_doc_max_bytes (32 KiB by default) (Codex docs). A long AGENTS.md can be silently cut.

The agents.md site says the format is now stewarded by the Agentic AI Foundation under the Linux Foundation.

What CLAUDE.md is

CLAUDE.md is the file Claude Code loads into every session as persistent instructions. It comes in four scopes: managed policy, user (~/.claude/CLAUDE.md), project (./CLAUDE.md or ./.claude/CLAUDE.md) and local (./CLAUDE.local.md, kept out of Git) (Claude Code docs).

Three details people miss, all from the same page:

• It's context, not enforcement. Claude tries to follow it but there's no guarantee. To block an action, the docs point to a hook or a permission rule instead.
• The docs target under 200 lines per file. Longer files use more context and reduce adherence.
• @path/to/file imports expand into context with the file that imports them. They help organization but don't save tokens.

What SKILL.md is

A SKILL.md file is the entry point of a skill, a folder that teaches the agent one task. It has YAML frontmatter, where name and description are required, followed by Markdown instructions (Agent Skills specification). Field-by-field details are in What is SKILL.md?.

The difference that matters here is loading. Per the spec, only the name and description (about 100 tokens per skill) load at startup. The body loads when the agent activates the skill, and files in scripts/ or references/ only when needed. The Claude Code docs make the same point: unlike CLAUDE.md content, a skill's body loads only when it's used, so long reference material costs almost nothing until you need it.

Do Claude Code and Codex read each other's file?

Not by default, and this is where most of the confusion comes from.

Sources: Codex docs (the fallback list is configurable in ~/.codex/config.toml) and Claude Code docs. The Claude Code page also says reading AGENTS.md directly needs v2.1.277 or later.

So a repo with both files makes Claude read only CLAUDE.md. If your team uses several agents, there are two documented ways to keep one source of truth:

1. Import. Put @AGENTS.md at the top of CLAUDE.md, then add Claude-specific lines below it.
2. Symlink. Run ln -s AGENTS.md CLAUDE.md. The docs warn that Windows checkouts may get a one-line text file instead of a link unless core.symlinks is enabled, and that Claude's Edit and Write tools won't write through a symlink.

The Skillpack repo itself uses the symlink approach, in the opposite direction: AGENTS.md is a symlink to CLAUDE.md (we checked in the repo on November 9, 2026). Symlinks come with the Windows caveat above, so check your own team's setup before copying it.

The rule for deciding where an instruction goes

Ask two questions about each line you're about to write.

1. Does the agent need it in every session? Build commands, test commands, repo layout, naming conventions, "never edit the generated folder": yes. Put it in AGENTS.md or CLAUDE.md.

2. Is it a procedure with steps, used for one kind of task? "How we cut a release", "how we review a migration": that's a skill. The Claude Code docs say it directly: if a CLAUDE.md entry is a multi-step procedure, or only matters for one part of the codebase, move it to a skill or a path-scoped rule.

A layout that works across agents

repo/
├── AGENTS.md                      # facts for every session, shared by all agents
├── CLAUDE.md                      # starts with @AGENTS.md, then Claude-only lines
└── .agents/skills/
    └── release/
        └── SKILL.md               # one procedure, loaded on demand

Skill folders differ by agent. Claude Code reads .claude/skills/, Codex reads .agents/skills/, and Cursor reads .agents/skills or .cursor/skills (Claude Code docs, Codex skills docs, Cursor docs). So the folder in the sketch above is the Codex and Cursor location. For Claude Code, the same skill needs to sit in .claude/skills/ as well. That duplication is the part that drifts, and a hub that installs one version into each folder removes it (try Skillpack). Our guide on skills across Claude Code, Codex and Cursor covers it, and so does how to share Claude Code skills with your team.

Mistakes we see most

• A 600-line CLAUDE.md. It costs context on every turn and, per the docs, lowers adherence. Split it into a short file plus skills and path-scoped rules.
• Procedures hiding in AGENTS.md. If the section starts with "step 1", it's a skill waiting to be extracted.
• Two files that disagree. The Claude Code docs warn that if two instructions contradict each other, Claude may pick one arbitrarily. Keep one source and import it.
• Using a text file for a hard rule. AGENTS.md and CLAUDE.md are context, not enforcement.
• Skipping the description in a skill. It's the only part the agent sees before deciding to load it. How to create a Claude Code skill shows how to write one that triggers.

When skills need a home of their own

AGENTS.md and CLAUDE.md live in your repo and travel with it. Skills are reused more widely: across repos, laptops and agents. That's where copies drift. Skillpack is an open-source Skills Hub for that one problem. You publish a SKILL.md package as an immutable, checksummed version, share it with your organization, and install an exact version into Claude Code, Codex or OpenCode with one command. It won't write your AGENTS.md, and you don't need it for a single-repo setup.

Once you have a few procedures worth reusing, create your Skillpack library and publish the first one.

FAQ