Why Most Claude Users Are Using Claude.md Wrong (And What to Do Instead)

Most Claude Code users do the same thing when they want Claude to follow a rule: they drop it into Claude.md.

That's the wrong move — at least half the time.

There's a second system most people ignore entirely: Skills. And the difference between the two isn't just technical. It changes how much your context costs, how reliably Claude follows instructions, and how cleanly your project stays organized as it grows.

Here's how to think about it.

The Core Problem With Putting Everything in Claude.md

Claude.md is always on. Every single conversation loads it, front to back, before a single word gets exchanged. That's by design — Claude.md is meant for context that's always relevant.

But here's the issue. Most developers stuff task-specific procedures in there too. Deployment steps. PR review checklists. Data migration guides. Things Claude only needs when you're doing a very specific job.

Every time those instructions load, they consume tokens. Whether you're asking Claude to fix a typo or spin up a full deployment pipeline, that entire block of text is sitting in context, paying a tax.

Claude.md has high context costs because it loads unconditionally. Skills have low context costs because only their description lives in context by default — the full instructions only load when they're actually needed.

That's the fundamental tradeoff.

How Skills Actually Work

A Skill is a file with a description at the top and the full procedure below it.

Claude reads the description and decides whether that Skill is relevant to the current task. If it's a match, the full Skill loads. If it's not, just the lightweight description sits in context. You get intelligent, on-demand loading instead of a dump of every instruction you've ever written.

The trigger mechanism is also different. Claude.md loads based on a simple rule: always. Skills load based on description matching — Claude evaluates whether the task at hand calls for that Skill, and pulls it in when it does.

This means Skills are much better suited for anything procedural, conditional, or task-specific.

The Sorting Logic: One Question

When deciding where something belongs, ask yourself one question:

Is this relevant to every conversation in this project, or only when I'm doing a specific thing?

If it's always relevant, it belongs in Claude.md.

If it only matters during a specific task, make it a Skill.

That's the whole framework. Here's what it looks like with real examples.

Five Real Examples

1. TypeScript strict mode → Claude.md

This is a project-wide standard. Every time Claude writes or reviews code in this repo, it needs to know you're using strict TypeScript. There's no scenario where this is irrelevant. It belongs in Claude.md.

2. PR review checklist → Skill

A checklist Claude should run through when reviewing a pull request is only needed when you're actually reviewing a PR. During every other conversation — debugging, writing tests, updating docs — it's dead weight in your context. Make it a Skill with a description like "PR review procedure for this codebase" and let it load on demand.

3. Use PNPM, not NPM → Claude.md

Package manager preference touches almost every task that involves dependencies. Installing packages, setting up environments, writing scripts — this context is always relevant. It belongs in Claude.md.

4. Deployment procedure → Skill

Your deployment steps might be detailed. Environment variable checks, build commands, migration order, rollback instructions. That's a lot of tokens to load every time you ask Claude to help you write a function. Make it a Skill. When you say "run the deployment procedure," Claude pulls it in. When you're doing anything else, it stays out of the way.

5. Never modify the database schema → Claude.md

This is a hard constraint on Claude's behavior that applies universally. It's not a procedure — it's a guardrail. You want it present in every single context so there's no ambiguity, no exceptions, no conversations where Claude didn't have this rule loaded. Claude.md is the right home.

What This Looks Like in Practice

Once you internalize the sorting logic, the pattern becomes fast:

• Standards, constraints, and permanent context → Claude.md

• Procedures, checklists, and task-specific instructions → Skills

Claude.md stays lean. It loads fast, stays focused, and everything in it is genuinely relevant to every conversation. Your Skills folder grows with your project — deployment, migrations, review procedures, testing workflows — and each one loads only when it's actually called on.

The result is a Claude setup that's cheaper to run, easier to maintain, and more reliable in practice because Claude isn't wading through irrelevant instructions to find the ones that matter.

The Takeaway

Claude.md isn't a dumping ground for everything you want Claude to know. It's a permanent context layer for project-wide truths. Skills are where your procedures live — ready when you need them, out of the way when you don't.

Most users never set up Skills at all. The ones who do have leaner contexts, lower token costs, and a much cleaner separation between "what Claude always knows" and "what Claude does when asked."

If you want the full breakdown on how to structure both — including how to write Skill descriptions that actually trigger reliably — drop "versus" in the comments and I'll send it over.