Skills, CLAUDE.md and MCP: what belongs in which
Three ways to give Claude Code context, and putting a thing in the wrong one is why it gets ignored. A short guide to which is which and when to reach for each.
The three mechanisms look interchangeable and are not. Most of the time something gets ignored, it is because it was put in the one that does not apply to the situation.
| Loaded when | Good for | |
|---|---|---|
CLAUDE.md | Always, in that project | Rules that are true for everything you do here |
| A skill | When its description matches | A job you ask for occasionally, by name or by outcome |
| An MCP server | When a tool it exposes is called | Reaching something live: a database, an API, a system |
The failure each one has
A rule in a skill that should have been in CLAUDE.md
You put the house style in a skill. It applies when the skill fires, which is sometimes, so half your output follows the rules and half does not, and it looks like the model being inconsistent rather than the rule being conditional.
A whole job in CLAUDE.md
The opposite problem. A long procedure in CLAUDE.md is read every turn in that project, whether you are doing that job or not, and it costs you the room for the job you are actually doing.
An MCP server for something that is just text
A server is a process. It has to be running, configured and kept alive on every machine that needs it. If what you needed was reference material, a folder of markdown does the same work and survives a reboot.
A test that settles most cases
Ask when the thing needs to be true.
- Always, in this repo, whatever I am doing:
CLAUDE.md. - When I ask for this particular job: a skill.
- When something outside the files has to be read or changed: MCP.
Rules that must always hold should not depend on whether a description matched.
Skills are the one of the three that travels: a folder of markdown and scripts, with nothing to run and nothing to configure. That is also why a skill works in anything that reads instructions from files, not only in Claude Code.
Questions
Should project conventions go in CLAUDE.md or in a skill?
CLAUDE.md, if they apply to everything you do in that repo. A skill is for a job you ask for by name occasionally. Rules that should always be true do not want to depend on whether something triggered.
When do I actually need an MCP server?
When Claude needs to call something live: query a database, hit an API, read a system it cannot reach through files. If the thing you need is instructions or reference text, a skill is simpler and has no process to keep running.
Can a skill and CLAUDE.md contradict each other?
Yes, and the result is unpredictable rather than an error. Keep the always-true rules in one place and have skills reference them instead of restating them.