CLAUDE.md vs AGENTS.md vs Skills: What Goes Where

The rule of thumb for claude.md vs agents.md vs skills is about timing, not tooling. If the agent needs an instruction on nearly every task, it belongs in an always-loaded instruction file, which is CLAUDE.md or AGENTS.md depending on the tool. If it matters only for some tasks, it belongs in a skill, which loads on demand.

The rest of this guide shows how each file loads, which agents read which, how to share one file across tools, and a short test you can run on any instruction to decide where it goes.

What each one is

AGENTS.md describes itself as a simple, open format for guiding coding agents, a README written for agents rather than people. It is plain Markdown with no required fields, usually holding setup commands, test instructions and pull request conventions.

CLAUDE.md is the Markdown file that gives Claude Code persistent instructions for a project, your personal workflow or your whole organization. Claude reads it at the start of every session.

A skill is a folder with a SKILL.md file, written to the open Agent Skills specification. Only the name and description are loaded up front, and the body loads when a task matches or you invoke the skill. What are Claude skills covers the format in detail.

Claude Code's own documentation draws the contrast directly. Unlike CLAUDE.md content, a skill's body loads only when it is used, so long reference material costs almost nothing until needed. A CLAUDE.md file, by contrast, is in context on every turn and has a recurring cost.

Which agents read which file?

This table sticks to what each vendor's documentation states.

Two patterns stand out. The instruction files differ by vendor, but the skills side is converging: .agents/skills is read by Codex, Cursor, Gemini CLI and Copilot. And AGENTS.md is the closest thing to a shared instruction file, since Codex, Cursor and Copilot's cloud agent read it directly.

How Codex, Cursor and Copilot load AGENTS.md

Codex builds an instruction chain by checking ~/.codex/AGENTS.override.md and then ~/.codex/AGENTS.md, then walking from the Git root down to your current directory. It includes at most one file per directory and concatenates them from the root down, so files closer to your working directory appear later and override earlier guidance. It stops adding files once the combined size reaches project_doc_max_bytes, which is 32 KiB by default.

Cursor treats AGENTS.md as a plain-Markdown alternative to its structured rules in .cursor/rules, and supports nested files where the more specific one takes precedence. GitHub's documentation says that when Copilot is working, the nearest AGENTS.md in the directory tree takes precedence.

How Claude Code loads CLAUDE.md and AGENTS.md

Claude Code loads CLAUDE.md and CLAUDE.local.md from your working directory and every directory above it, and concatenates them from the filesystem root down. Files in subdirectories load on demand, when Claude reads or edits a file there. Imports use @path/to/file syntax and expand at launch, so they organize a long file without shrinking its context cost.

For AGENTS.md, the documented default is the claude-md-or-agents-md setting: Claude reads AGENTS.md only when there is no CLAUDE.md or CLAUDE.local.md in your working directory or any directory above it. That catches people who add a personal CLAUDE.local.md to a repository that relies on AGENTS.md, because Claude then stops reading AGENTS.md. Setting Project instructions to claude-md-and-agents-md in /config makes it read both.

How Gemini CLI loads GEMINI.md

Gemini CLI concatenates GEMINI.md files from a global location, the workspace and just-in-time directories, and supports @file.md imports. The file name is configurable: the context.fileName setting in settings.json accepts a single name or an array such as ["AGENTS.md", "CONTEXT.md"].

How do you share one file across agents?

Keep the shared rules in AGENTS.md, then add a thin CLAUDE.md that imports it. Anthropic's documentation shows this pattern:

@AGENTS.md

## Claude Code

Use plan mode for changes under `src/billing/`.

Claude reads the imported file first, then the Claude-specific notes below it. A symlink from CLAUDE.md to AGENTS.md also works, with two caveats from the same documentation. Claude's edit tools will not write through a symlink and will instead edit the target. And on Windows, creating symlinks needs elevated rights or Developer Mode, and Git can check a committed symlink out as a plain text file, so the import is the safer choice there.

For Gemini CLI, set context.fileName to include AGENTS.md. For Copilot, the cloud agent already reads it. This means one reviewed file can serve four tools, with each tool's own file reserved for notes that apply to it alone. If you are moving from Cursor or Copilot, Claude Code's /init command reads Cursor rules and .github/copilot-instructions.md and folds the relevant parts into a new CLAUDE.md.

Where should each instruction go?

Run any instruction through these questions in order.

1. Does the agent need it on almost every task? Build and test commands, directory layout and naming conventions go in AGENTS.md or CLAUDE.md.
2. Does it apply to only one part of the codebase? Scope it. Claude Code has path-specific rules in .claude/rules/ with a paths field, Cursor has rules that apply to specific files, and Copilot has .instructions.md files with glob patterns. A nested AGENTS.md in a subdirectory also works.
3. Is it a multi-step procedure or long reference material? Make it a skill. Release steps, a migration checklist or an API reference would otherwise sit in context all day.
4. Must it be enforced, not just encouraged? Instruction files are context, not configuration. Claude Code's documentation says to use a hook if an action must be blocked regardless of what the model decides.

A few worked examples:

How long should an instruction file be?

Claude Code's documentation targets under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence. It recommends concrete, checkable instructions such as "Use 2-space indentation" over "Format code properly", and warns that contradictory instructions across files can lead Claude to pick one arbitrarily. Codex enforces a hard cap through project_doc_max_bytes.

The documentation also says when to add to the file: when the agent makes the same mistake twice, when a code review catches something it should have known, or when you retype the same correction each session. If an entry is a multi-step procedure, it suggests moving it to a skill. That is the same boundary this guide draws, and it is the reason a bloated instruction file is a sign you need skills. The comparison with other extension types is in Claude skills vs MCP, plugins and subagents.

Which directory skills help with instruction files?

The agent instructions topic lists skills that maintain these files. These are described from their listings, each with its licence and automated safety result, and we have not run them ourselves.

• Neat-Freak Knowledge Closeout brings project docs, agent rule files and workspace leftovers back in line with what the code does at the end of a session. MIT.
• Caveman Memory File Compressor rewrites a memory file such as CLAUDE.md in terse text to cut input tokens, keeping a readable backup. Apache-2.0. Its safety result carries informational notes, so read the notes on its page.
• Agent Context Engineering sets up what an agent sees, from rules files to relevant specs. MIT, also with informational safety notes.
• SkillOpt Sleep Cycle reviews past Claude Code sessions and proposes validated updates to CLAUDE.md and skills. MIT.

To turn a long section of your instruction file into a skill, start with Skill Creator, and see the SKILL.md format reference for the file layout. For agent memory beyond instruction files, there is also the agent memory topic. Installing the result in Claude Code is covered in how to add skills to Claude Code.