CLAUDE.md: what belongs in it, what to cut, and a file you can copy

Most CLAUDE.md files are a README with a new name. Directory tree, tech stack, a paragraph about the company mission. All of it gets loaded on every single message, and almost none of it changes what Claude does.

The file has one job: stop Claude making the same wrong assumption twice. Everything else in there is rent you pay on every turn.

Below is what belongs in a CLAUDE.md file, what to cut, a complete example you can copy, and where the file sits next to AGENTS.md, SKILL.md and project instructions.

What the CLAUDE.md file is

CLAUDE.md is a plain markdown file that Claude Code reads automatically at the start of a session. No command, no import, no configuration. If the file is there, its contents are in context.

It can live in a few places, and they stack:

• Project root. ./CLAUDE.md, checked into the repo, shared with everyone on the team. This is the main one.
• Your home directory. ~/.claude/CLAUDE.md applies to every project you open. Personal preferences go here, not in the repo.
• Subdirectories. A CLAUDE.md deeper in the tree gets picked up when Claude works on files in that area. Useful in a monorepo where one package has rules the others do not.
• CLAUDE.local.md, gitignored, for anything you do not want your colleagues inheriting.

Running /init in a repo generates a first draft by reading the codebase. Treat that draft as a starting point rather than a finished file, because it tends to describe the project instead of instructing Claude.

Why the length of the file is the whole game

Here is the part most guides skip. Everything in CLAUDE.md is loaded on every message, whether or not it is relevant. A 2,000-word file is 2,000 words competing for attention with the thing you actually asked.

The failure mode is not that Claude ignores a long file. It is subtler. Claude follows the parts it can see clearly and drifts on the rest, which reads like the file working intermittently. Then you add another line to fix the drift, the file grows, and the drift gets worse.

A CLAUDE.md that fits on one screen outperforms a thorough one almost every time. If yours is longer than about 400 words, most of what is in there is reference material, and reference material belongs in a file the model can open when it needs it.

What belongs in CLAUDE.md

Six categories, roughly in order of value:

1. Commands that are not guessable. How to run tests, build, lint and start the dev server in this repo specifically. This is the single highest-value content in the file.
2. Conventions that contradict the obvious default. If your codebase does something unusual, say so. If it does the standard thing, leave it out; Claude already assumes the standard thing.
3. Boundaries. Files and directories not to touch. Generated code, vendored dependencies, anything with a migration path.
4. The definition of done. Tests pass, types check, no new lint warnings. Whatever your bar is, written as something checkable.
5. Gotchas that cost you time before. The flaky test, the service that needs an env var, the build step that fails silently. Each of these earns its line by having burned someone.
6. When to stop and ask. Schema changes, anything touching auth, anything that would add a dependency. The clause that prevents the most damage.

What to cut

1. The directory tree. Claude can list files. It does not need a map that goes stale the week after you write it.
2. The tech stack. Reading package.json takes one tool call and is never out of date.
3. Anything about who you are as a company. It does not change a single line of code.
4. Praise and personality. "You are an expert senior engineer" costs tokens on every message and changes nothing.
5. Style rules your linter already enforces. If the formatter fixes it, the model does not need to know it.
6. Long explanations of architecture. Write those in a doc and point at it. Claude will open it when the work needs it.

The test for any line: has this specific instruction changed an output? If you cannot remember it mattering, delete it and see whether anything gets worse.

A CLAUDE.md example you can copy

This is roughly the shape I use. Under 300 words, and every line is there because something went wrong without it.

# CLAUDE.md

## Commands
- Test: `pnpm test` (single file: `pnpm test path/to/file`)
- Typecheck: `pnpm typecheck`. Must pass before any commit.
- Dev: `pnpm dev` (needs `.env.local`, copy from `.env.example`)
- Migrations: `pnpm db:migrate`. Never edit a file in `migrations/`
  that has already run.

## Conventions that differ from the default
- We use `zod` schemas as the source of truth for types. Derive types
  from schemas, never write them by hand.
- API handlers return `Result<T, AppError>`, never throw.
- Dates are stored UTC and formatted only at render.

## Do not touch
- `src/generated/` (regenerated, edits are lost)
- `packages/legacy-billing/` (frozen, has its own owner)

## Done means
Tests pass, typecheck clean, no new lint warnings, and the diff
contains nothing I did not ask for.

## Gotchas
- `auth.test.ts` is flaky in CI, not in local. Rerun before debugging.
- The seed script silently no-ops if the DB already has rows.

## Ask me first
- Any schema change
- Any new dependency
- Anything touching `src/auth/`

Notice what is absent. No stack description, no folder map, no mission statement, no compliments.

CLAUDE.md vs AGENTS.md

AGENTS.md is the vendor-neutral version of the same idea, adopted across several coding agents so one file works in more than one tool. Claude Code reads it as well as CLAUDE.md.

Practical advice: if your repo is worked on with more than one agent, put the shared content in AGENTS.md and keep CLAUDE.md for anything Claude-specific, or have CLAUDE.md point at AGENTS.md rather than duplicating it. Two files with overlapping instructions is worse than either alone, because when they drift apart you will not notice until the output is wrong. Tooling in this area moves quickly, so check the current docs before restructuring around it.

CLAUDE.md vs SKILL.md vs project instructions

File	Loads	Holds
CLAUDE.md	Every message, automatically	Standing facts about one codebase
SKILL.md	Only when a request matches its description	A procedure with steps
Project instructions	Every message inside one project	Standing facts about a body of work

The reason this matters: anything you put in CLAUDE.md is paid for constantly, and anything you put in a SKILL.md is paid for only when it is used. If a section of your CLAUDE.md only applies to one kind of task, it wants to be a skill.

The SKILL.md format

A skill is a folder with a SKILL.md at the top. The file opens with YAML frontmatter carrying two required fields, then the body in markdown.

---
name: migration-writer
description: Use when adding, altering or dropping a database column
  and a migration file needs writing, including requests phrased as
  "add a field to X" or "we need a new column". Not for querying
  existing data or for schema design discussions.
---

# Migration writer

## Steps
1. Read the current schema in `src/db/schema.ts` before writing.
2. Write the up migration. Write the down migration in the same pass.
3. Never edit a migration that has already run; add a new one.
4. Run `pnpm db:migrate` against the local DB and report the output.

## Gotchas
- Adding a NOT NULL column to a populated table needs a default or a
  three-step migration. Say which one you are doing and why.

## Good looks like
The migration runs clean, the down migration reverses it exactly, and
the schema file matches the result.

If you want agent skills examples to read before writing your own, the library linked at the end is the fastest way in; the structure above is the pattern all of them follow.

Claude keeps every installed skill's name and description in view at all times, and opens the body only when a request matches. That is why the description is the most important line in the file, and why the body can be as long as it needs to be.

What makes a description fire

Descriptions written as topic labels do not fire. "Helps with database migrations" names a subject; it does not name a moment. Descriptions written as situations do fire, and the ones that fire most reliably include the sloppy phrasings a real person would type.

Add a "not for" clause pointing at the nearest neighbouring skill. Two skills with overlapping descriptions and no exclusions is a coin toss about which one activates.

How to create a Claude skill

Three ways, in ascending order of effort:

Write it by hand. Make a folder, write a SKILL.md with the two frontmatter fields, put it in .claude/skills/ for one project or ~/.claude/skills/ for all of them. Ten minutes.

Use skill-creator. Anthropic's official skill scaffolds a new one and tests whether the description actually triggers on realistic phrasings. It is the fastest route to a working file, and the trigger test is the part worth having. Install it from Anthropic's skills repository on GitHub.

Start from one that works. Take a skill close to what you want, keep its structure, replace the steps. The structure is most of the value.

Whichever route, test it the same way: open a new conversation, phrase a request in your own words, and see whether the skill fires. If it does not, the description is wrong. The body is almost never the problem.

Questions people ask

How long should a CLAUDE.md file be?

Under 400 words. Every word is loaded on every message, so length has a running cost and a real effect on how reliably the file is followed.

Does CLAUDE.md work in Claude.ai, or only Claude Code?

It is a Claude Code convention. The equivalent in Claude.ai is project instructions, which behave the same way inside a project.

Can I have more than one CLAUDE.md?

Yes. Home directory, project root and subdirectories all stack. Keep personal preferences in the home one so they do not end up in the repo.

What is the difference between a skill and a plugin?

A skill is one folder with instructions. A plugin bundles skills with commands and other configuration so a team can install the set at once.

Do I need both CLAUDE.md and AGENTS.md?

Only if more than one agent works in the repo. If it is Claude alone, one file is simpler and stays consistent.

Where to take this next

The quickest win is subtraction. Open your CLAUDE.md, delete the directory tree and the stack description, and see whether anything gets worse. In my experience nothing does.

For working SKILL.md files to start from, the free skill library has 108 of them, single-purpose and free to modify. THE INDEX catalogues 141 across 14 domains with install notes for Claude, Copilot, Gemini and Grok, and there is a separate Grok Bot Skill Vault of 32.

If you would rather have the whole setup built for your actual job rather than assembled from parts, that is what The Pack does: nine files, project instructions plus eight task files, install paths for Claude, ChatGPT, Gemini, Copilot and Grok.