How long should CLAUDE.md be? What to keep and what to move into skills

Claude Code is Anthropic's coding tool. You type a request, and an AI model reads files, runs commands and edits code for you. CLAUDE.md is a text file of instructions that you write and that Claude reads at the start of every session. All of this work is counted in tokens. A token is a piece of text that the model processes, and every request you send is measured in tokens.

This page belongs to the guide on how to reduce Claude Code token usage. It answers one question: how long should CLAUDE.md be, and where should the rest of your instructions go? The short answer, from Anthropic's documentation read on 4 October 2026, is under 200 lines for each file [1]. The longer answer is that Claude Code gives you several places to put an instruction, and most of them keep the full text out of the conversation until it is needed.

Why the length of CLAUDE.md matters

The context window is the text the model can read in one request. It holds your instructions, the files Claude has read and every earlier message. Anthropic's documentation, read on 4 October 2026, says that each session begins with a fresh context window and that Claude reads your CLAUDE.md files at the start of every session [1].

The file then stays there. The model keeps nothing between two requests, so Claude Code sends the full context again each time, and the project context is part of it [4]. Anthropic's cost page states the result plainly: if CLAUDE.md contains detailed instructions for specific procedures, "those tokens are present even when you're doing unrelated work" [3]. A line about database changes is sent with a request to fix a spelling mistake.

Anthropic's simulation of a session gives example sizes. In it, a project CLAUDE.md is 1,800 tokens and a personal CLAUDE.md in the home folder is 320 tokens [5]. Anthropic calls these representative counts, so they are examples and your files will differ. The same simulation shows a second cost. A subagent is a second copy of Claude that works on one task in its own separate context window. A subagent loads its own copy of the project CLAUDE.md, another 1,800 tokens that the simulation counts in the subagent's own context window. The built-in Explore and Plan agents skip the file [5].

The prompt cache lowers the price of this repeated text. The prompt cache is a store of request text that the service has already processed, and text read from it is billed at a lower rate [4]. The tokens are still counted on every request. The related guide explains what the prompt cache is.

Length has a second effect, separate from tokens. The documentation says that longer files "consume more context and reduce adherence", which means Claude follows them less reliably [1]. Claude treats CLAUDE.md as context. The documentation says there is "no guarantee of strict compliance, especially for vague or conflicting instructions" [1]. A short file uses fewer tokens, and by Anthropic's account Claude follows it more consistently.

Anthropic's guidance: under 200 lines for each file

Three of Anthropic's pages give the same figure. The memory page says: "target under 200 lines per CLAUDE.md file" [1]. The cost page says: "Aim to keep CLAUDE.md under 200 lines by including only essentials" [3]. The simulation's note beside the project file says: "Keep it under 200 lines" [5].

The 200-line figure is a target. Claude Code loads a CLAUDE.md file of up to 4 MiB in full and skips a larger file, by the same documentation [1]. Text past line 200 still loads. Claude Code shows a warning when one of your instruction files is over the recommended length, at startup and when you run /status. A second warning appears when files that are each within the length add up past a combined limit at session start, and each CLAUDE.md, rules file and imported file counts as a separate file [1]. The documentation does not state the number for that combined limit.

Three tools help you measure and shorten the file, all by Anthropic's account on 4 October 2026:

• /context shows what is in the context window by category. The list under Memory files names each CLAUDE.md that loaded [1].
• /doctor proposes cuts to a CLAUDE.md that is stored with the project. The proposal cuts content Claude can work out from the code, such as lists of folders and lists of the outside code packages the project uses, and keeps warnings, reasons and conventions that differ from tool defaults. This check requires Claude Code v2.1.206 or later [1].
• /doctor prompt-audit looks for instructions that are out of date or that contradict each other, and reports proposed edits. It requires Claude Code v2.1.283 or later [1].

One detail saves tokens with no loss. Notes for human readers can go inside an HTML comment, written as <!-- note --> on its own lines. Claude Code removes these comments before the content enters the context [1].

What belongs in CLAUDE.md

The documentation gives a direct rule: "Keep it to facts Claude should hold in every session: build commands, conventions, project layout, 'always do X' rules." [1] It also lists four moments to add a line [1]:

• Claude makes the same mistake a second time.
• A code review finds something Claude should have known about this project.
• You type the same correction that you typed in the last session.
• A new member of the team would need the same information.

Write each instruction so that it can be checked. The documentation's examples are "Use 2-space indentation" in place of "Format code properly", and "Run npm test before committing" in place of "Test your changes" [1]. The same page says that Claude follows specific, concise instructions more consistently [1].

The same paragraph of the documentation says what to move out: "If an 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 instead." [1] The next sections explain both.

Where to put an instruction

This table is the comparison this page exists for. Every row comes from Anthropic's documentation, read on 4 October 2026 [1][2][5].

Place	When it enters the context	What it adds while unused	Use it for
CLAUDE.md in the project root (the top folder of the project) or your home folder	At the start of every session	The full text, in every request	Facts every session needs: build commands, conventions, "always do X" rules
Rule file in .claude/rules/ with no paths field	At launch, like CLAUDE.md	The full text, in every request	Splitting a long file by topic so people can maintain it
Rule file with a paths field	When Claude reads, writes or edits a matching file	Nothing	Instructions for one file type or one folder
CLAUDE.md inside a subfolder	When Claude reads a file in that subfolder	Nothing	Instructions for one part of a large project
Skill	Description at the start, body when the skill is used	Its name and description	Step-by-step procedures, such as a release or a database migration
Hook	Runs as a command at a fixed event	Only what the hook reports back	A rule that must run every time

Skills: procedures that load when used

A skill is a set of instructions for one task, stored in a file named SKILL.md. Anthropic's skills page, read on 4 October 2026, says to create one when a section of CLAUDE.md has grown from a fact into a procedure, and states the difference in cost: "Unlike CLAUDE.md content, a skill's body loads only when it's used" [2]. The cost page gives two examples of instructions to move: reviews of proposed code changes and database migrations [3].

A skill still has a small fixed cost. Claude Code loads a listing of skill names and descriptions so that Claude knows what is available [2]. In Anthropic's simulation this listing is 450 tokens [5]. The skills page gives three limits on it [2]:

• Each skill's description is cut at 1,536 characters in the listing.
• The whole listing has a size limit equal to 1% of the model's context window.
• When the listing is over that limit, Claude Code drops descriptions, starting with the skills you use least.

You can remove even the description. A skill marked disable-model-invocation: true stays out of the context completely until you call it by typing / and its name [5]. Anthropic recommends this setting for skills that change something outside the conversation, such as a skill that releases software or sends a message [5]. The /skill-doctor command, which requires Claude Code v2.1.252 or later, reports what each skill costs and how often it is used [2].

Two cautions apply. First, a loaded skill stays in the conversation across later turns, so the skills page says "every line is a recurring token cost" and advises keeping SKILL.md under 500 lines [2]. In the simulation, one skill that the user calls adds 620 tokens [5]. Second, a skill is the wrong place for a fact that every session needs, because its body loads only when you call it or when Claude judges it relevant to your request [1].

Path rules, nested files and imports

A path rule is a file in the .claude/rules/ folder that names the files it applies to. The names go in a short block of settings at the top of the file, between two lines of three hyphens. This shortened example follows the form in Anthropic's documentation [1]:

---
paths:
  - "src/api/**/*.ts"
---

- All API endpoints must include input validation

The rule loads when Claude uses its Read, Write or Edit tool on a file that matches the pattern [1]. Until then it adds nothing. In Anthropic's simulation, two path rules of 380 and 290 tokens load in this way, each at the moment Claude reads a matching file [5]. A rule file with no paths field is different: it loads at launch with the same priority as .claude/CLAUDE.md, so it saves no tokens [1].

A nested CLAUDE.md works in a similar way. A CLAUDE.md file in a subfolder below the folder where you started Claude Code is held back at launch and included when Claude reads files in that subfolder [1].

Imports work the other way. A CLAUDE.md file can include another file with the @path/to/import form, and an imported file can import further files, up to four levels deep. The documentation says imported files "are expanded and loaded into context at launch", and that imports "help you organize a long file but don't reduce its context cost" [1]. In an invented example, splitting a 600-line file into three imported files of 200 lines each leaves 600 lines in every request.

Path rules and nested files have one weakness. Compaction is the step where Claude Code replaces the older conversation with a summary to free space. After compaction, the project-root CLAUDE.md is read from disk again, while path rules and nested files are summarised with the rest of the conversation and load again only when Claude next reads a matching file [5]. The documentation's advice: if a rule must persist across compaction, remove the paths field or move the rule to the project-root CLAUDE.md [5]. The page on /clear, /compact and /rewind covers what else is kept.

Auto memory loads at the start too

CLAUDE.md is one of two files that load at the start. The other is auto memory, a set of notes that Claude writes for itself from your corrections and preferences. It is on by default in local sessions [1].

The first 200 lines of its index file, MEMORY.md, or the first 25KB, whichever comes first, load at the start of every conversation. Detailed notes are kept in separate topic files that Claude reads only when it needs them [1]. In Anthropic's simulation the loaded part is 680 tokens [5].

Run /memory to read, edit or delete these notes, or to turn auto memory off. To turn it off for one project, set autoMemoryEnabled to false in that project's settings [1]. One habit matters here. When you tell Claude to remember something, it saves the note to auto memory. To add a line to CLAUDE.md, say so directly, for example "add this to CLAUDE.md" [1].

An edit during a session waits for /clear, /compact or a restart

Anthropic's documentation on prompt caching, read on 4 October 2026, describes a behaviour to know before you shorten the file: "Your project-root and user-level CLAUDE.md files are read once at session start and held in memory." An edit during the session has no effect on that session. Claude keeps working with the version that loaded at the start, and the new content loads on the next /clear, /compact or restart [4].

Nested CLAUDE.md files and path rules follow a different schedule. An edit made before the file loads does take effect. After the file loads, its content is part of the conversation history, and a later edit leaves that history unchanged [4].

So after you shorten CLAUDE.md, run /clear or start a new session, then run /context and check the Memory files list. The page on how to read /usage and /context explains that screen. The related guide lists this edit among the actions that keep the cache.

Our position

Keep the project CLAUDE.md under 200 lines, and treat each line as a cost that is added to every request. For each line, ask one question: would Claude need this in a session about a different part of the project? Then sort the lines.

1. Keep a line if every session needs it. Build commands and naming conventions pass this test.
2. Move a step-by-step procedure into a skill. If the procedure changes something outside the conversation, mark it disable-model-invocation: true so that its description stays out of the context as well.
3. Move an instruction for one folder or one file type into a rule with a paths field.
4. Move a rule that must run every time into a hook. A hook is a command that Claude Code runs by itself at a fixed point, such as after each file edit. The documentation says hooks "apply regardless of what Claude decides to do" [1]. The page on hooks that trim output shows one in full.
5. Use imports for tidiness only. They save no tokens.

Reveneau is an AI software development consultancy, and all of its code is written by AI, so token use is a running cost of every Reveneau build. Reveneau recommends reviewing the project CLAUDE.md on a fixed schedule, because the file is shared with the whole team and loads in every session each person starts. Reveneau is independent of Anthropic. Every figure on this page is Anthropic's own statement about its own product, and the page on where Claude Code tokens go shows how this file compares with the rest of the context.