Claude MD vs skills
Claude MD vs skills comes down to timing. Your CLAUDE.md file loads at the start of every session, while a skill loads only when a task needs it.
TL;DR: Put short facts Claude must always know in CLAUDE.md. Move long procedures and reference docs into skills. Keep CLAUDE.md under about 200 lines.
What is a CLAUDE.md file?
CLAUDE.md is a plain markdown file of standing instructions for Claude Code. Claude reads it at the start of every session.
It holds the things you would otherwise explain again and again. Think build commands, test commands, folder layout and "always do X" rules.
A project file lives at ./CLAUDE.md and is shared with your team through git. A personal file at ~/.claude/CLAUDE.md applies to all your projects. You can run /init to have Claude draft a first version from your codebase. Anthropic's memory docs list every location and how each one loads.
What is a Claude skill?
A skill is a folder with a SKILL.md file inside. It teaches Claude one kind of task, like a release checklist or your API style guide.
Claude sees only each skill's short description at first. The full body loads when a task matches, or when you type /skill-name. Until then, a long skill costs almost nothing.
Skills can also carry scripts and reference files. Our step-by-step skill guide shows the folder format.
What is the difference between CLAUDE.md and skills?
The core difference is when each one loads. CLAUDE.md is always on. A skill waits until it is needed.
| Question | CLAUDE.md | Skill |
|---|---|---|
| When does it load? | Every session, automatically | On demand, when relevant or invoked |
| What should it hold? | Short facts and rules | Procedures and reference material |
| Can you run it as a command? | No | Yes, with /skill-name |
| Where does it live? | ./CLAUDE.md or ~/.claude/CLAUDE.md | .claude/skills/name/SKILL.md |
| What does it cost in context? | Its full size, every session | A short description until used |
Think of CLAUDE.md as the notes taped to your monitor. A skill is the binder on the shelf. You read the notes all day, and you pull the binder only when the job calls for it.
When should something go in CLAUDE.md?
Use CLAUDE.md for facts that matter in nearly every task. Good examples are "use pnpm, not npm" or "run npm test before committing."
Anthropic's advice is to add a line when Claude makes the same mistake twice. A repeated review comment is another good sign.
Keep each line concrete. "API handlers live in src/api/handlers/" works better than "keep files organized." Claude treats CLAUDE.md as guidance, not a hard rule. If something must happen every time, use a hook instead.
When should something become a skill?
Make a skill when an entry turns into a multi-step procedure. If you paste the same playbook into chat a third time, it is time.
Reference docs are a strong fit too. A long API guide in CLAUDE.md costs context in every session, even when you never touch the API. As a skill, it loads only for API work.
Skills also give you a command. A /deploy or /release skill runs the same steps each time, in front of you, where you can steer.
How do I know my CLAUDE.md is too long?
A good limit is about 200 lines. Anthropic's guide to Claude Code features gives this rule of thumb. Longer files use more context, and Claude follows them less reliably.
Watch for a few signs. Sections only matter for one part of the codebase. Steps read like a recipe. Or two rules contradict each other.
To trim it, move each procedure into a skill. Move rules for one folder or file type into .claude/rules/, which can load only for matching paths. What stays should be short, true and needed every day.
Can a skill help me write CLAUDE.md?
Yes. Several skills in the SkillTrove catalog work on CLAUDE.md itself.
The agent-memory skill by Alireza Rezvani is built for a CLAUDE.md that has grown past what anyone reads. It only promotes a fact to a committed file after it recurs across sessions and a human adopts it.
His memory-review skill audits Claude's auto memory. It flags stale entries and suggests which ones to promote.
Sentry's agents-md skill takes a strict line on size. It aims for an instruction file under 60 lines and never over 100. It checks that every path and command it writes exists. It also says to keep one source file: make AGENTS.md the real file and symlink CLAUDE.md to it, rather than keeping two copies. The source is in the getsentry/skills repo.
If your repo needs a lean, checked instruction file, that skill is a good place to start.
View the agents-md skill by Sentry
FAQ
Should I use CLAUDE.md or skills?
Use both, for different jobs. CLAUDE.md is for short facts Claude needs in every session, like build commands and naming rules. Skills are for procedures and reference docs Claude needs only sometimes, like a deploy checklist. A simple test is to ask whether Claude needs the line on most tasks. If yes, keep it in CLAUDE.md. If no, move it to a skill so it stops using context in every session.
Does Claude read CLAUDE.md every time?
Yes. Claude Code loads CLAUDE.md files at the start of every session. Files in your working directory and above load at launch. Files in subfolders load when Claude works in those folders. Run /context during a session to see which memory files loaded. Skills work differently: only their short descriptions load up front, and the full text loads when used.
Can skills replace CLAUDE.md?
Not fully. A skill only loads when a task matches it or you call it, so it can miss rules that apply everywhere. Facts like your package manager or test command still belong in CLAUDE.md. What skills can replace is the long middle of a bloated CLAUDE.md: procedures, checklists and reference docs that only some tasks need.
What is the difference between AGENTS.md and CLAUDE.md?
Both are instruction files for coding agents. AGENTS.md is a shared format many agents read, while CLAUDE.md is the file Claude Code reads first. Claude Code can read AGENTS.md when a repo has no CLAUDE.md. If you need both, keep one real file and import or symlink the other, so the two never drift apart. Neither one is a skill.