Notes on coding agents and the pages they leave behind, on moving between notes apps, and on the plain mechanics of keeping what you think. Written and published from a Sumibako vault.
CLAUDE.md, AGENTS.md, MEMORY.md and skills: what goes in which file, and what belongs in none of them
CLAUDE.md vs AGENTS.md vs MEMORY.md vs skills: who reads each, how much gets loaded, the CLAUDE.local.md trap, and what belongs in none of them.
Prashant Shaw
Founder, Sumibako
9 min read
The CLAUDE.md in the repository behind this site is 261 lines and 68 KB. Anthropic's documentation says to "target under 200 lines per CLAUDE.md file. Longer files consume more context and reduce adherence." Codex, if I renamed it AGENTS.md, would stop reading at 32 KiB, which is somewhere around the part about payments. And my MEMORY.md, the file Claude writes about me, is 51 lines and 19.7 KB, a few kilobytes from the point where the rest of it falls off. So I am not writing this as somebody who got it right. I am writing it as somebody who finally read the manuals.
There are now four kinds of file a coding agent reads before it does anything, and the search box has noticed: "claude md vs agents md vs skills" is a thing people type. This post is what each file is for, who reads it, how much of it gets read, and the one kind of thing that belongs in none of them. Everything was checked on 3 November 2026 against Anthropic's, OpenAI's and Cursor's own documentation.
Codex, Cursor, and Claude Code when there is no CLAUDE.md
MEMORY.md
Claude
Every session, first 200 lines or 25KB
An index of what Claude learned about you
Claude Code, on one machine
A skill (SKILL.md)
You, or Claude
Name and description at start, body when used
Procedures
Claude Code, Codex and Cursor, from different folders
The fine print on each row is where the surprises are.
📜 CLAUDE.md: facts, every session
Anthropic's memory page is clear about what it is for: "Keep it to facts Claude should hold in every session", which in practice means build commands, conventions, project layout and the rules you would otherwise repeat. The same page has the best trigger I have seen for adding a line: when "Claude makes the same mistake a second time".
Three details are worth knowing before you add anything:
1️⃣ It is advice, not a lock. "Claude treats them as context, not enforced configuration." The file is delivered as a message after the system prompt, and the more it says, the less of it is followed.
2️⃣ The whole file loads. The 200-line figure is a target, not a cut-off: Claude Code reads a CLAUDE.md up to 4 MiB and skips one larger than that entirely. Imports with @path organise a long file but, in the docs' words, "don't reduce its context cost". Nobody stops you writing 261 lines; your context window pays for each of them, every session.
3️⃣ Comments are free. Block-level HTML comments are stripped before the file reaches Claude. "Use them to leave notes for human maintainers without spending context tokens on them." I learned this about a year too late.
Anthropic's post on steering Claude Code puts the cost bluntly: "Every line loads into every session for every engineer working in the repo, whether it's relevant to their task or not."
🤝 AGENTS.md: the same file, for everyone else
AGENTS.md is the vendor-neutral version, "used by over 60k open-source projects", and its own pitch is the best summary: "Think of AGENTS.md as a README for agents". Codex, Cursor, Gemini CLI, Copilot's coding agent and a long list of others read it. It is plain Markdown with no required fields.
Each tool reads it slightly differently, which is the part nobody tells you:
Codex builds a chain from ~/.codex/AGENTS.md down through each directory to where you started, one file per directory, with an AGENTS.override.md winning over an AGENTS.md beside it. It "stops adding files once the combined size reaches the limit", which is 32 KiB by default (OpenAI's guide). Past that, your instructions are simply not there.
Cursor reads AGENTS.md in the root and in subdirectories, alongside its own .cursor/rules/*.mdc files. Its rules page is refreshingly direct about the trade: "If you prefer plain markdown, use AGENTS.md instead."
Claude Code reads AGENTS.md since version 2.1.277, but with a condition. "By default, Claude reads AGENTS.md only when you have no CLAUDE.md in your working directory or above it."
That condition has a trap in it, and the docs admit it in one sentence: "Because CLAUDE.local.md counts, adding one to keep your own uncommitted instructions in a project that relies on AGENTS.md stops Claude from reading AGENTS.md for you." Create a private file of personal notes, and the shared instructions quietly vanish. The fix is to set Project instructions to claude-md-and-agents-md in /config.
💡TIP
The arrangement that works in all three tools: put the shared facts in AGENTS.md, and make CLAUDE.md two things, the line @AGENTS.md and whatever is only for Claude below it. Anthropic documents exactly this and confirms the import never makes Claude read AGENTS.md twice. A symlink from CLAUDE.md to AGENTS.md also works, except on Windows, where Git checks a committed symlink out as a one-line text file unless symlinks are enabled.
🧠 MEMORY.md: the one you don't write
MEMORY.md is not an instruction file at all. It is the index of Claude Code's auto memory, which lives at ~/.claude/projects/<project>/memory/, and Claude writes it, not you. It saves four kinds of note: who you are, corrections you gave it, project decisions it cannot read from the code, and where to find things outside the repository.
The limits are precise: the first 200 lines of MEMORY.md, "or the first 25KB, whichever comes first, are loaded at the start of every conversation." The notes it points to load only when Claude goes looking. And it is deliberately narrow: "Claude skips anything it can derive from the codebase, such as architecture, file paths, or debugging fixes. It also skips anything your CLAUDE.md files already say."
Two consequences people miss. First, "Auto memory is machine-local." Your laptop's Claude knows you prefer pnpm; your desktop's Claude has never met you. Second, it survives the 30-day transcript sweep I wrote about in where Claude Code keeps your conversation history: the memory folder is excluded and stays until you or Claude delete it. It is also nothing to do with the memory in the Claude app, which is a different feature with different rules and a post of its own.
So the CLAUDE.md or MEMORY.md question has a simple answer. If you would say it to a new teammate, write it in CLAUDE.md. If Claude noticed it about you, let Claude keep it, and read the folder now and then with /memory, because you should know what it says about you.
🧰 Skills: procedures, loaded when needed
A skill is a folder with a SKILL.md in it: a name, a description, and instructions. The difference from everything above is when it loads. Only the name and description sit in context; "a skill's body loads only when it's used, so long reference material costs almost nothing until you need it." Anthropic's skills page says to create one "when you keep pasting the same instructions, checklist, or multi-step procedure into chat", and the steering post has my favourite line in the whole set: "A 30-line procedure in CLAUDE.md. Procedures belong in skills."
Skills are an open standard, which caps a description at 1,024 characters and suggests keeping SKILL.md under 500 lines. In practice the folders differ:
.agents/skills/, .cursor/skills/, and "for compatibility", Claude's and Codex's folders too (Cursor)
Cursor, for once, is the diplomat. For Claude Code and Codex, keep one copy and link each skill folder into the other location; both document following a linked skill folder.
The description is the part that matters most, because it is how the agent decides to load the skill at all. Claude Code cuts the description and its trigger text off at 1,536 characters in the listing, and when you have many skills it drops descriptions from the ones you use least. Put the use case in the first sentence. After a compaction, Claude Code re-attaches the skills you invoked, "keeping the first 5,000 tokens of each. Re-attached skills share a combined budget of 25,000 tokens", so a long skill is a skill whose end is forgotten first.
Rules sit between the two: .claude/rules/ files with a paths: list load only when Claude touches matching files. If a CLAUDE.md line only matters in src/api/, it is a rule, not a fact.
🚧 What belongs in none of them
1️⃣ Anything that must never fail. Anthropic's extension overview says it plainly: an instruction not to edit .env in CLAUDE.md or a skill "is a request, not a guarantee." The steering post: "A real guardrail needs to be deterministic". That is a hook or a permission deny rule, and an hour spent writing one beats a year of capital letters in CLAUDE.md.
2️⃣ Anything the code already says./doctor now flags "checked-in CLAUDE.md content Claude could derive from the codebase", which is a polite way of saying your directory tree does not need a paragraph.
3️⃣ Your personal habits, in a shared file. That is what ~/.claude/CLAUDE.md, CLAUDE.local.md and ~/.codex/AGENTS.md are for. Your teammates do not need to load your love of semantic commit messages.
4️⃣ The state of the work. What this branch is for, what was decided on Tuesday and why, what was tried and rejected, what is half done. None of the four files is built for it. CLAUDE.md and AGENTS.md are read by every session forever, so a plan put there is obeyed long after it is finished. MEMORY.md is Claude's to edit, on one machine, and keeps what Claude judges useful. A skill is a procedure, not a diary. And the conversation, where this context actually lives, is what compaction summarises away.
The work belongs in a document: a file in docs/, a GitHub issue, or a page outside the repository that the agent writes and you can read without opening a terminal. I make Sumibako for the last one: Claude Code, Codex and Cursor file a page with one command, Claude.ai through a connector, and a new session reads it back by its key. It works on the free plan. It does not load itself at session start the way CLAUDE.md does; the skill tells the agent when to read and write, which is, fittingly, a procedure in a skill.
🧭 The one-question test
When you are about to add a line somewhere, ask when the agent needs to know it.
If the agent needs it
Put it in
In every session, in this repo, whichever agent
AGENTS.md, imported by CLAUDE.md
In every session, Claude only
CLAUDE.md, below the import
Only when working in certain files
A rule with paths:
Only when doing a particular job
A skill
Every time, without exception
A hook or a deny rule
Because it learned it about you
Leave it to auto memory
To carry on this piece of work tomorrow
A document, outside all of the above
And if your CLAUDE.md is 261 lines long, move the procedures into skills before you write a blog post telling other people to. I have started. It is going about as well as a closet clear-out usually does.
