Guide
Claude Code skills vs CLAUDE.md vs MCP
These look like four ways to give an agent instructions. They are really four different jobs. The difference that matters most is when each one loads, because that sets what it costs you in context.
The decision table
| CLAUDE.md | Skill | Slash command | MCP server | Hook | |
|---|---|---|---|---|---|
| Job | Facts about the project | A procedure or domain knowledge | A prompt you run by name | Tools to reach outside systems | A rule that must run |
| Loads | Every session, at launch | Listing always; body on use | When you run it | Tool names listed; details as needed | On the event it watches |
| Context cost | Full text, every session | About 100 tokens, then the body when used | Only when run, if set to manual-only | Tool definitions, plus every result | None, it runs outside the model |
| Agent decides | Always sees it | Yes, from the description | No, you invoke it | Yes, it chooses tools | No, the harness runs it |
| Enforced | No | No | No | No | Yes |
| Use when | Build commands, conventions, layout | A repeatable task done the same way | A shortcut you type | The agent needs data or actions elsewhere | Something must always or never happen |
Claude Code's docs say custom commands have merged into skills, so a file in .claude/commands/ and a skill in .claude/skills/ both create a slash command. A skill adds supporting files and finer control over who can invoke it. The MCP column reflects the docs on tool search, which lists tool names first so that the full detail is not loaded for tools that are not used.
What it costs, measured
The same text costs different amounts depending on where you put it. Below are real free skills. If the body sat in CLAUDE.md, you would pay the whole body every session. As a skill, you pay the description every session and the body only when it triggers. Tokens are the scanner's estimate.
| Skill | In CLAUDE.md, every session | As a skill, every session | As a skill, when used |
|---|---|---|---|
| Taste Core | 951 tokens | 83 tokens | 1,034 tokens |
| Hyperframes Starter | 1,055 tokens | 94 tokens | 1,149 tokens |
| Humanizer | 1,024 tokens | 104 tokens | 1,128 tokens |
| Grill Me | 1,075 tokens | 91 tokens | 1,166 tokens |
| Prospect Brief | 952 tokens | 87 tokens | 1,039 tokens |
A skill you use in most sessions closes the gap, and the always-loaded cost of many installed skills adds up. Claude Code's docs advise keeping a CLAUDE.md under about 200 lines because longer files use more context and reduce how well instructions are followed. See reduce skill token usage for how to trim.
Which to reach for
| You want to… | Use |
|---|---|
| Tell the agent how to run tests in this repo | CLAUDE.md |
| Make it write release notes the same way every time | A skill |
| Run a prompt you retype often | A skill or slash command |
| Let it query your issue tracker | An MCP server |
| Block pushes to main without review | A hook |
| Teach it how to use that MCP server well | A skill that names the tools |
A good CLAUDE.md is short. The free AGENTS.md Architect writes one from your real repo. For what makes a skill worth writing, see how to write a skill, and for how the loading works, progressive disclosure.
Sources
Questions
- What is the difference between a skill and CLAUDE.md?
- CLAUDE.md is loaded at the start of every session, so everything in it costs context every time. A skill's body loads only when it is used, so long procedures cost almost nothing until needed. Claude Code's docs suggest making a skill when a CLAUDE.md section has grown into a procedure rather than a fact.
- Are slash commands and skills the same thing now?
- In Claude Code, yes. Its docs say custom commands have merged into skills: a file at .claude/commands/deploy.md and a skill at .claude/skills/deploy/SKILL.md both create /deploy, and existing command files keep working.
- When should I use MCP instead of a skill?
- When the agent needs to reach something outside your files: a database, an API, another app. MCP gives it tools. A skill gives it knowledge and a procedure. They combine well: a skill can tell the agent how to use an MCP server's tools.
- Can CLAUDE.md enforce a rule?
- No. Claude Code's docs say it treats CLAUDE.md as context, not enforced configuration, and recommend a hook for anything that must always run or never happen.
Keep reading
- Skill ScannerScore any skill in your browser. Nothing is uploaded.
- SKILL.md format referenceEvery field, its limit, the folder layout and the errors people hit.
- Reduce skill token usageWhat a skill costs in context, a token estimator, and a trim you can copy.
- Progressive disclosure for skillsThree levels of loading and how to split a skill across them.
- All guidesEvery guide, grouped by what you are trying to do.
Paste a SKILL.md or drop a folder. It is scored in your browser and nothing is uploaded.
Want a skill that already passes? Start with a free one.
AGENTS.md ArchitectFreeScan 100/100A short instructions file from your real repo. From the Agent Ops collection.