CLAUDE.md vs AGENTS.md vs SKILL.md: What Goes Where and Why

Anyone who starts using Claude Code tends to create a CLAUDE.md and stuff everything into it: project setup, coding rules, pull request etiquette, stack details, onboarding notes. Then AGENTS.md enters the conversation, followed by SKILL.md, and it looks like three files for the same job. They aren't. Mixing them up means paying for tokens that did nothing for you.

A quick mental model

Picture a company. CLAUDE.md is the employee handbook that every new hire reads on day one, always in the background. AGENTS.md is the same handbook, written so outside contractors from any agency can follow it, not only the permanent staff. SKILL.md is a manual on a shelf that you take down only when you're doing that specific task. Three files, three jobs and three loading patterns.

CLAUDE.md: always loaded

This is Claude Code's main configuration file. At session start, Claude reads it and holds it in its system prompt. It's loaded once, becomes part of the context used throughout the session, and doesn't need to be fetched from disk with each message. So when you type a greeting, those instructions are present, and they're present again when you later ask for a bug fix.

The consequence is that a large file permanently occupies part of the context window, including on tasks where most of it is irrelevant. That's why a focused, short file pays off.

Three levels

Instructions come from several scopes and are combined:

1. A personal file at ~/.claude/CLAUDE.md, holding preferences that apply across every project, like indentation style or commit message habits. Teammates never see it.
2. A project file, either .claude/CLAUDE.md or one at the repository root. It's committed to Git, so everyone who clones the repo gets the same rules. Stack details, commands and team standards belong here.
3. Path-specific rules, stored under .claude/rules/ with a paths setting in the frontmatter. A testing-rules file, for example, can load only while test files are being edited, which keeps irrelevant guidance out of context.

More specific project guidance is loaded after broader user-level instructions, so when the two conflict, the project's version can win. The practical rule: personal taste goes in personal config, shared team conventions go in the project.

What belongs inside

Keep it short. Staying under about 200 lines is a reasonable target, though that's a guideline and not a hard limit. Include only what Claude needs on every task: the tech stack, the commands that run tests and start the dev server, absolute rules like never logging user data, and the major architecture decisions.

Leave out anything task-specific. A long guide to reviewing a PR or a catalog of edge cases has a better home, which comes up below.

A gotcha

Edit CLAUDE.md mid-session and the running session won't notice. The file was read once at the start, so a new session is required for changes to apply. It's the most common reason a freshly added rule seems ignored.

AGENTS.md: for teams with several tools

AGENTS.md serves the same purpose, holding project context and instructions. What differs is who can read it. Claude Code reads CLAUDE.md, while OpenAI Codex, Cursor, Gemini CLI and GitHub Copilot read AGENTS.md.

Claude Code doesn't natively pick up AGENTS.md, as far as this describes it, but a symlink solves that by pointing both names at one file (check the current docs in case support has changed):

ln -s AGENTS.md CLAUDE.md

Now there's a single file, every tool reads it and nothing drifts apart.

When it's needed

If the whole team uses only Claude Code, CLAUDE.md is enough. If people use a mix of tools, or if CI runs a different agent from the one developers use locally, AGENTS.md becomes your single source of truth across all of them.

Silent instruction loss

Multi-agent pipelines have a nasty failure mode. Imagine one stage runs in Claude Code and another in a tool from a different vendor. If your rules live only in CLAUDE.md, the second tool ignores them without any error or warning. The agent runs normally but doesn't follow the conventions you assumed were in force. Output gets inconsistent, behavior drifts, and since nothing looks broken, the cause is hard to find. Using AGENTS.md as a shared baseline lets every tool in the pipeline see the same rules.

SKILL.md: loaded on demand

This one works differently. The other two load at the start of each session and stay in context. A skill loads only when the current task matches its description.

A skill is a folder containing a SKILL.md. The file opens with a short YAML header giving the skill a name and a one-line description, and that description is what Claude reads to judge whether the skill fits. When you send a message, Claude compares it with the descriptions of all your skills and loads whichever matches. When the task ends, the skill is dropped. Here is what frontmatter can look like:

---
name: pr-review
description: Use when the user asks to review a pull request or check code quality.
allowed-tools: [Read, Grep, Glob]
---

Why that saves tokens

Say you've documented ten workflows. Put all ten in CLAUDE.md and all ten load on every message, even a request to fix a typo. As skills, only the relevant one loads and the other nine cost nothing. In long sessions that mix different task types, that keeps context lean and aimed at the work in front of you.

The description matters most

Claude relies on the description to choose. A vague one like "helps with code" will either never fire or fire for everything. A precise one, such as reviewing Python pull requests for vulnerabilities like SQL injection or hardcoded secrets, triggers reliably and only when relevant. The folder name is for you. The description is for Claude, so write it for Claude.

Two useful frontmatter options

allowed-tools limits what Claude can do while the skill is active. For a skill that explores a codebase, setting it to read, grep and glob lets Claude look around without editing or writing files, and the restriction applies even if you ask for an edit.

context: fork runs the skill's work in an isolated context. Intermediate steps stay hidden and only the final result returns to the main session, which suits tasks that generate lots of content you don't need to read, such as scanning fifty files for one summary.

Keep skills compact too

A big skill eats more context once loaded. If a workflow needs heavy documentation, examples or reference material, put those in separate files and have the skill pull them in as needed. The main instructions should stay on the workflow itself.

Comparing the three

How to choose

• A rule that applies to every task in every session goes in CLAUDE.md.
• If the team uses several AI coding tools, or the pipeline mixes them, make AGENTS.md the source of truth and link CLAUDE.md to it.
• A specific workflow you repeat, like reviewing PRs, producing a resume or searching documentation, should become a skill.
• If Claude must stay read-only for a workflow, make it a skill with allowed-tools.
• If you want to trigger something by hand with one command, use a slash command in .claude/commands/.

A tidy layout

your-project/
├── AGENTS.md                   <- shared source of truth for all tools
├── CLAUDE.md                   <- imports AGENTS.md, adds Claude-specific rules
├── .claude/
│   ├── rules/
│   │   ├── testing.md          <- loads only when editing test files
│   │   └── security.md         <- loads only when editing auth-related files
│   ├── skills/
│   │   ├── pr-review/
│   │   │   └── SKILL.md        <- loads when you ask for a PR review
│   │   └── latex-resume/
│   │       └── SKILL.md        <- loads when you ask to build a resume
│   └── commands/
│       └── standup.md          <- /standup generates your daily update
└── ~/.claude/
    └── CLAUDE.md               <- your personal preferences, not in the repo

CLAUDE.md stays short because it holds only what every task truly needs. Skills carry the heavy, task-specific workflows. AGENTS.md makes sure things still work when a teammate switches tools.

Rule of thumb

If CLAUDE.md runs past 200 lines, or beyond roughly 1,200 to 1,500 tokens, you're likely paying on most messages for instructions you don't need. Sort by when each instruction is needed: always means CLAUDE.md, across tools means AGENTS.md, only for one kind of task means a skill. Your context window is a budget. The main file spends some of it on every message, while skills spend only when used, so design the setup around that.