Claude Code AGENTS.md vs Skills vs Agents: What Goes Where

Claude Code now reads AGENTS.md on its own (v2.1.277 and later), but only when the project has no CLAUDE.md. If you have both files, put @AGENTS.md at the top of CLAUDE.md so Claude reads the shared file. The rule of thumb for everything else: instruction files for facts every session needs, skills for procedures loaded on demand, subagents for side work in a separate context, hooks for rules that must always hold, and MCP for outside tools.

The decision table

Every row is based on the current Claude Code memory, skills and subagents docs.

I want…	Use	Where it lives	When it loads
Build commands, conventions and architecture notes for every tool and every session	`AGENTS.md`	Repo root (and subfolders)	Every session
Claude-specific instructions on top of that	`CLAUDE.md` that imports `@AGENTS.md`	`./CLAUDE.md` or `./.claude/CLAUDE.md`	Every session
My personal preferences in this repo, not committed	`CLAUDE.local.md`	Repo root, gitignored	Every session
Rules that apply only to some files (say, `src/api/**`)	Path-scoped rules	`.claude/rules/*.md`	When Claude works on matching files
A repeatable procedure or checklist (release, migration, PDF report)	Skill	`.claude/skills/<name>/SKILL.md`	Description always, body on demand
A command I trigger myself, like `/deploy`	Skill with `disable-model-invocation: true`	`.claude/skills/deploy/SKILL.md`	Only when I type it
A worker that reads a lot and sends back only a summary	Subagent	`.claude/agents/<name>.md`	When Claude delegates to it
Something that must always (or never) happen	Hook	`settings.json`	At lifecycle events, every time
Access to an outside system (Notion, a database, an internal API)	MCP server	`.mcp.json` or `claude mcp add`	Tools found through tool search

CLAUDE.md: the instructions Claude reads every session

CLAUDE.md is plain Markdown that Claude reads at the start of each session. Claude Code loads it from your working directory and every directory above it, plus ~/.claude/CLAUDE.md for personal instructions and an optional organization-managed file. A subdirectory's CLAUDE.md loads once Claude touches a file in that subdirectory. All of them are concatenated, not overridden, and files closer to where you launched are read last.

Three points from the docs that shape what belongs here:

Keep it short. The docs suggest under 200 lines per file, because longer files use more context and Claude follows them less reliably. Imports (@path/to/file) help organize a file but don't save context, since imported files load along with it.
It is context, not enforcement. In the docs' words, "to block an action regardless of what Claude decides, use a PreToolUse hook instead."
Procedures belong elsewhere. The skills docs suggest creating a skill when "a section of CLAUDE.md has grown into a procedure rather than a fact."

AGENTS.md: the file other coding agents read

AGENTS.md is an open format, described as "a README for agents." It is plain Markdown with no required fields, it is stewarded by the Agentic AI Foundation under the Linux Foundation, and the site lists more than 20 tools that read it, including OpenAI Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, Zed, Aider and Devin. Suggested sections are a project overview, build and test commands, code style, testing instructions and security notes.

How Codex reads it: one global file in ~/.codex, then one file per directory from the project root down to your working directory. In each directory it checks AGENTS.override.md first, then AGENTS.md. The combined instructions are capped at 32 KiB by default (project_doc_max_bytes).

Does Claude Code read AGENTS.md?

Yes, with conditions. The Claude Code docs spell them out:

Your repository has	Claude reads
`AGENTS.md` and no `CLAUDE.md` or `CLAUDE.local.md` in the working directory or above	`AGENTS.md`
`AGENTS.md` and a `CLAUDE.md` or `CLAUDE.local.md`	Only the `CLAUDE.md` files
A `CLAUDE.md` that imports `@AGENTS.md`	Both, through the import

Some details that catch people out:

Adding a personal CLAUDE.local.md to a repo that relies on AGENTS.md stops Claude from reading AGENTS.md. Your ~/.claude/CLAUDE.md and .claude/rules/ don't have that effect.
Claude Code doesn't read AGENTS.override.md, AGENTS.local.md or anything under .agents/.
You can change the default in /config under Project instructions: claude-md-or-agents-md (default), claude-md-and-agents-md, claude-md or managed-only.
Older versions, and sessions where the built-in plugin that reads AGENTS.md is turned off, read only CLAUDE.md.

The bridge that works in every case is a CLAUDE.md that imports the shared file and adds Claude-only notes underneath:

@AGENTS.md

## Claude Code

Use plan mode for changes under src/billing/.
Run the test suite with the verify skill before you say a task is done.

A symlink (ln -s AGENTS.md CLAUDE.md) also works, but the docs list two catches. Claude's Edit and Write tools won't write through the link. And on Windows, Git checks out a committed symlink as a one-line text file unless core.symlinks is enabled. If anyone on the team uses Windows, use the import. Either way, run /context all and check that the file appears under Memory files.

Skills: procedures loaded on demand

A skill is a folder with a SKILL.md file: YAML frontmatter that says when to use it, then instructions, plus optional scripts and reference files. Claude sees the name and description of every skill at all times, but the body loads only when the skill is used. That is why the docs say long reference material in a skill "costs almost nothing until you need it." You can call a skill yourself with /skill-name, or Claude can pick it when a task matches the description.

Locations: ~/.claude/skills/<name>/ for personal skills, .claude/skills/<name>/ for project skills you commit, and a managed directory for the whole organization. Two settings change who can trigger a skill. disable-model-invocation: true means only you can run it, which suits anything with side effects such as deploys. context: fork runs the skill in its own subagent.

Slash commands are skills now

Claude Code docs: "Custom commands have been merged into skills." A file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy. Old command files keep working. Use skills for new work, because they can include supporting files.

Skills across tools

Claude Code skills follow the Agent Skills open standard, and Codex uses the same SKILL.md format, also loading only names and descriptions until a skill is chosen. The folders differ, though. Codex scans .agents/skills in the repo and ~/.agents/skills. Claude Code reads .claude/skills. Claude Code follows a symlinked skill folder, so you can keep one copy and link it into both places. For portable frontmatter, stick to the spec's fields: name, description, license, compatibility, metadata and allowed-tools. Claude Code extensions such as context: fork cause a hard error when you upload the skill to claude.ai or the Skills API. More on this in our Agent Skills standard guide and Claude Code skills best practices.

Subagents: separate context for side work

A subagent is a Markdown file in .claude/agents/ (project) or ~/.claude/agents/ (personal). Its frontmatter sets the name, description, tools and model, and the body is its system prompt. The docs say each subagent "runs in its own context window with a custom system prompt, specific tool access, and independent permissions." Use one when a side task would fill your main conversation with search results or logs you won't need again. Subagents count toward the same usage limits as your main session.

---
name: code-reviewer
description: Reviews diffs for correctness and missing tests. Use after any change to src/.
tools: Read, Glob, Grep
model: sonnet
---

You are a code reviewer. Do not edit files. Report concrete findings with file and line.

Skills vs agents in one line: a skill adds instructions to the agent that is already working. A subagent hands the work to a separate worker with its own context and returns only the result. Codex has its own version: TOML files in .codex/agents/ with name, description and developer_instructions. See Codex CLI commands and subagents for details, and agent teams vs swarms if you need several agents working together.

Hooks and MCP

Hooks are shell commands, HTTP endpoints, prompts or MCP tool calls that Claude Code runs at fixed points in a session, such as before a tool runs. You define them in settings.json. Use a hook when an instruction keeps being ignored and has to hold every time, for example "never edit generated files" or "run the formatter after every write." Claude can skip an instruction in CLAUDE.md. A hook runs no matter what Claude decides.

MCP servers give Claude tools for outside systems. Add one with claude mcp add --transport http <name> <url>, or commit it in .mcp.json so the team shares it (each person approves project servers the first time). Tool search is on by default, so Claude looks tools up when it needs them instead of loading every definition up front.

A repo layout that works in Claude Code and Codex

my-app/
├── AGENTS.md                  # shared: overview, build/test commands, conventions
├── CLAUDE.md                  # "@AGENTS.md" plus Claude-only notes
├── .agents/
│   └── skills/
│       └── release/
│           ├── SKILL.md       # spec-only frontmatter: name, description
│           └── scripts/bump_version.py
├── .claude/
│   ├── skills/
│   │   └── release -> ../../.agents/skills/release   # symlink, one source
│   ├── agents/
│   │   └── code-reviewer.md   # Claude Code subagent
│   ├── rules/
│   │   └── api.md             # path-scoped: loads for src/api/**
│   └── settings.json          # permissions, hooks
├── .codex/
│   └── agents/
│       └── code-reviewer.toml # Codex subagent
├── .mcp.json                  # shared MCP servers for Claude Code
└── src/
    └── payments/
        └── AGENTS.md          # extra rules for this package

The shared skill keeps to the standard:

---
name: release
description: Cut a release. Use when the user asks to release, tag or publish a new version. Do not use for hotfix branches.
---

1. Run the full test suite; stop if anything fails.
2. Run scripts/bump_version.py with major, minor or patch.
3. Update CHANGELOG.md from the merged PR titles since the last tag.
4. Commit, tag vX.Y.Z and show the user the push command. Do not push.

One thing to check: Claude Code reads a subfolder AGENTS.md such as src/payments/AGENTS.md only when it is reading AGENTS.md files at all, and only if that folder has no CLAUDE.md of its own. Because this layout has a root CLAUDE.md, set Project instructions to claude-md-and-agents-md, or add a CLAUDE.md with @AGENTS.md in that folder too.

Common mistakes

Writing procedures into CLAUDE.md. A 600-line file full of deploy steps costs context in every session. Move the steps into a skill.
Vague skill descriptions. The description is how Claude decides to use a skill. Say when to use it and when not to. With many skills installed, Claude Code shortens descriptions to fit a budget of 1% of the context window, starting with the skills you use least.
Using a subagent for a checklist. If the work needs your current conversation's context, a skill is a better fit. Subagents start without your conversation history.
Relying on instructions for safety. Use permission rules and hooks. For secrets, see Claude Code API key setup and secret safety.

Keeping the setup in sync across machines and teammates

Project files (AGENTS.md, .claude/, .agents/) travel with the repo. Personal skills and agents in ~/.claude don't, and that is where most useful know-how ends up: a skill you refined over months, or a reviewer agent tuned to how you work. Skylls publishes each skill, agent or swarm to its own private GitHub repo with versions and a secret scan before every push. You then share each item with specific people:

skylls push release -m "Stop before pushing tags"
skylls share release @teammate

Your teammate installs it with skylls add release, for Claude Code, Codex or Gemini CLI. If you run Claude Code and Codex agents side by side, Hivey coordinates them from one terminal, and the shared AGENTS.md plus the linked skills above means every agent in the swarm starts with the same rules.

Next step: move one procedure out of your CLAUDE.md into a skill this week, then publish it with Skylls so your other machines and your team get the same version.