CLAUDE.md vs SKILL.md: What Goes Where in Claude Code
If you use Claude Code, you've probably put something in CLAUDE.md that didn't belong there. A long deployment checklist. Testing steps. A migration guide you wrote once and never opened again. It still works, Claude rea
If you use Claude Code, you've probably put something in CLAUDE.md that didn't belong there. A long deployment checklist. Testing steps. A migration guide you wrote once and never opened again. It still works, Claude reads it. But it also sits in your context window on every single turn, even when you're just asking Claude to rename a variable.
That's the real difference between CLAUDE.md and SKILL.md. It's not about what the content is. It's about when it should load. CLAUDE.md loads at the start of every session, always. SKILL.md only loads when it's actually needed. Get this right, and your agent stays fast and focused. Get it wrong, and you're paying for information on every message that you only need once a week.
I spend my days building multi-agent systems coordinating planner, executor, and validator agents, wiring in guardrails, keeping humans in the loop where it matters. Claude Code is one of my daily tools, and this context problem is one of the first things I clean up when a setup starts feeling sluggish or unfocused. Here's how I think about it.
Key Takeaways
- CLAUDE.md loads every time a session starts. SKILL.md only loads when you or Claude actually invoke it.
- CLAUDE.md is for facts that are always true, conventions, build commands, how your project is laid out.
- SKILL.md is for procedures, the multi-step things you'd otherwise explain over and over.
- Anthropic's own advice: if part of your CLAUDE.md reads like a set of steps instead of a fact, move it into a skill.
- Skills can carry scripts and reference files that stay out of context until Claude actually needs them. CLAUDE.md can't do that.
What CLAUDE.md Is For
CLAUDE.md is a plain markdown file that gives Claude standing instructions for one project, for your own workflow, or for your whole team. Claude Code reads it automatically at the start of every session (Anthropic, Memory documentation). No command needed. It's just there before you type your first message.
That "always there" quality is what makes it useful for a narrow kind of information: things that stay true no matter what you're working on that day. Your naming conventions. Which command actually starts the app. The rule that pull requests need a ticket number. If you'd tell this to a new team member on their first day, and it wouldn't change next month, it belongs in CLAUDE.md.
Claude Code also has a second memory system that works alongside this one: auto memory, where Claude writes its own notes based on corrections and preferences it picks up while working with you (Anthropic, Memory documentation). You don't write this one, Claude decides what's worth keeping. Think of CLAUDE.md as the memory you write on purpose, and auto memory as the memory Claude builds on its own.
Where people get this wrong
The usual mistake isn't about content, it's about length. A CLAUDE.md file works best when it stays short and stable, a set of facts, not a growing document. Once it turns into something closer to a manual, a model has too many things to hold onto at once, and it starts missing the instructions that actually matter.
Anthropic's own guidance points to the fix directly: when part of a CLAUDE.md file starts to look like a "multi-step procedure" instead of a plain fact, that section belongs somewhere else in a skill, or in a rule scoped to a specific part of the project (Anthropic, Memory documentation).
What SKILL.md Is For
A skill is a small folder with one required file, SKILL.md, inside it. That file has two parts: a short description at the top telling Claude when to use it, and instructions below telling Claude what to do once it runs. You can trigger a skill yourself by typing /skill-name, or Claude can pick it up on its own when your request matches the description (Anthropic, Skills documentation).
Here's the part that matters most: a skill's instructions only enter context when the skill actually runs. Long reference guides, edge cases, whole templates none of it costs you anything until the moment you need it. That's a genuinely different way of managing cost, not just a different place to store the same notes.
Anthropic draws a clean line between two kinds of skill content: reference material Claude applies while working ("these are our API conventions"), and task instructions that walk through a specific job ("deploy the app") (Anthropic, Skills documentation). Skills can also do things CLAUDE.md simply can't run scripts instead of just describing them, pull in live command output before Claude even sees the prompt, or run inside an isolated subagent so a research task doesn't clutter your main conversation.
What a skill looks like
Here's a small example, based on Anthropic's own getting-started guide:
---
description: "Summarizes uncommitted changes and flags anything risky. Use when the user asks what changed, wants a commit message, or asks to review their diff."
---
## Current changes
!`git diff HEAD`
## Instructions
Summarize the changes above in two or three bullet points, then list any risks such as missing error handling or hardcoded values.
That !`git diff HEAD` line runs before Claude even sees the prompt. Claude Code runs the command first and drops the real output into the skill. So the skill shows up with your actual changes already there, not just instructions for how to go find them.
CLAUDE.md vs SKILL.md: Side by Side
How to Decide Which One to Use
I think about this in terms of how often something changes and how often it's used, not what topic it's about.
Use CLAUDE.md when it's always true and rarely changes. Your code style rules. Your folder structure. The fact that every pull request needs a ticket number. If it's something you'd tell a new team member on day one, and it won't be different next month, it's memory, not a skill.
Use a skill when it's a set of steps you run sometimes, not constantly. Deploying to a test environment. Writing a commit message from a diff. Fixing a numbered issue. Building a visual report. These all have a clear start and end, that's exactly what skills are built for.
Use a skill (not CLAUDE.md) for reference material you only need once in a while. Detailed guides, style references, onboarding notes for one part of a system. A skill can point to extra files that load only when needed. CLAUDE.md has no way to do this, anything you put there loads every time, whether you need it that day or not.
Make a skill manual-only if it has real consequences. You don't want Claude deciding on its own that it's time to deploy or send a message just because the code looks ready. Setting a skill to manual-only means it only runs when you type the command yourself.
They Work Together, Not Against Each Other
This isn't a choice you make once and forget. A well-set-up Claude Code project usually uses both, and they point to each other. Your CLAUDE.md can be short and simply say "for deployment steps, see the deploy skill," while the actual deploy skill stays out of context until you need it. That's the same idea Anthropic recommends for CLAUDE.md itself, and it's also how skills should be structured once they grow: keep the main file short, and move detail into separate files it links to.
The real mistake isn't picking the wrong file once. It's not noticing that your CLAUDE.md has slowly turned into a procedure manual, one paragraph at a time, until every session is carrying steps nobody needs that day.
Frequently Asked Questions
Does Claude re-read CLAUDE.md during a session, or only at the start? Only at the start. Claude Code loads it fresh each time a session begins, but it doesn't check back mid-session the way a skill can be called again. If you edit CLAUDE.md while working, start a new session to make sure the change is picked up.
Can a skill see what's in CLAUDE.md? Usually, yes. Skills run inside your normal conversation, so they see whatever's already loaded, including CLAUDE.md. The one exception is a skill that runs as an isolated subagent for research or planning, those are built to skip CLAUDE.md on purpose, to keep their context small.
What happens if I put a long procedure in CLAUDE.md by mistake? Nothing breaks right away. But every session pays for those extra lines, whether you're doing that task or not. The higher cost is that it crowds out the instructions that actually matter every time a model can only hold so many standing rules at once.
Where should personal preferences go? Keep personal, cross-project preferences in your own CLAUDE.md, separate from the project-level file your team shares. Keep it short - coding style, language preference, habits you want in every project.
Can I stop Claude from using a skill on its own? Yes. You can set a skill to manual-only, so it only runs when you type the command yourself. Or you can set it so only Claude can use it, and it won't show up as something you'd run directly. Either way, you're in control of it.
If you're setting up Claude Code for a team and want a second opinion on what belongs in memory versus a skill, I'm always happy to compare notes.
Originally published by Dev.to AI. Aggregated on AIWithGhost for educational purposes β full credit and traffic to the original publisher.