In Claude Code, when should an instruction live in a skill rather than in CLAUDE.md?
answer
- load timing differs
- every session versus on demand
- a procedure, not a fact
- the description still sits in the listing
- both are guidance, not enforcement
basics
~20 sCLAUDE.md loads into every session, so it suits short always-true facts and rules; a skill loads its body only when invoked by /name or matched by its description, so it suits procedures and long reference material needed sometimes.
solid answer
~40 s`CLAUDE.md` is read at launch, stays in every request and is re-read from disk after compaction, so it should hold short facts and rules every task needs: build commands, conventions, "always do X". A skill is a `SKILL.md` whose body enters context only when you type `/name` or Claude matches its `description` to the task, so it suits multi-step procedures, checklists and long reference material that is needed only sometimes. A good trigger: a CLAUDE.md section has grown into a procedure, or you have pasted the same playbook into chat a third time. A model-invocable skill is not free, because its name and description sit in the skill listing every turn, and neither file enforces anything: a rule that must always hold needs a hook or a permission rule.
go deeper
Recall the core split: CLAUDE.md loads every session, while a skill's body loads only when invoked by /name or matched by its description. Give one example of content for each.
Explain the context cost precisely: the listing entry every model-invocable skill carries, the full body that stays once invoked, and how disable-model-invocation removes the listing cost.
Show you have pruned a bloated CLAUDE.md: which sections became skills or path-scoped rules, how you checked each skill still fires, and why must-hold rules went to hooks instead.
Frame it as a context budget for a team: what earns always-on space, what loads on demand, and how you stop shared instruction files from quietly growing back.
## Two instruction files, two loading models Claude Code gives you two main places to write standing guidance for Claude. **`CLAUDE.md`** is project memory: Claude Code reads it, together with the `CLAUDE.md` files in the directories above where you started, at launch, and the text stays in every request of the session. A **skill** is a folder containing a `SKILL.md` file, under `.claude/skills/<name>/` for a project or `~/.claude/skills/<name>/` for you personally, whose body is loaded only when it is used. You run it by typing `/name`, or Claude loads it on its own when your request matches the skill's `description`. That one difference, always loaded against loaded on demand, drives almost every decision about where content goes. ## What each one costs in context | | CLAUDE.md | Skill (default) | Skill with `disable-model-invocation: true` | | :- | :- | :- | :- | | Before anyone uses it | Full text, every request | Name and description in the skill listing, every request | Nothing | | When used | Already there | Full body enters the conversation and stays | Full body enters the conversation and stays | | After auto-compaction | Re-read from disk | Re-attached, capped at 5,000 tokens per skill and 25,000 in total | Same as a default skill | | Pulling in other files | `@path` imports, expanded at launch | Supporting files it points to, read when needed | Same as a default skill | Two consequences follow: - **Reference material is expensive in CLAUDE.md.** An API style guide or a schema description there costs tokens on every turn of every session, even when the task never touches it. In a skill it costs one listing entry until it is needed. - **A skill is not free either.** A model-invocable skill's name and description are listed every turn so Claude can choose it. Only `disable-model-invocation: true` removes that cost, and it also stops Claude from loading the skill on its own, so it fits manual workflows only. ## Signals that content belongs in a skill - It is a **procedure**: release steps, a review checklist, an incident playbook. The docs suggest making a skill when a CLAUDE.md section "has grown into a procedure rather than a fact". - You keep **pasting the same instructions** into chat to start a task. - It is **reference material needed sometimes**, such as the full API conventions or a vendor's error codes. - You want a **command**: `/release` or `/triage` that you or Claude can start by name. - It needs **live data**: a skill can inject a command's output with `` !`command` `` before Claude reads it; CLAUDE.md cannot run anything. ## Signals that content belongs in CLAUDE.md - **Facts every task needs**: how to build and test, the directory layout, naming conventions. - **Short "always" and "never" rules** that apply whatever Claude is doing. - Keep the file small. The docs' rule of thumb is under 200 lines; move procedures and reference material into skills, or into path-scoped rules when they apply only to part of the codebase. The two combine well: CLAUDE.md says "follow our API conventions", and a skill holds the full style guide that loads when Claude works on an endpoint. ## Moving a section out of CLAUDE.md 1. Find a section that reads as steps or as a reference rather than as a fact. 2. Create `.claude/skills/<name>/SKILL.md` and move the text into its body. Keep the body concise, since once loaded it stays in context; the docs suggest keeping `SKILL.md` under 500 lines and moving detail into supporting files. 3. Write a `description` that leads with the use case, in the words people actually type. 4. Start a fresh session and check both that `/name` works and that Claude loads the skill on a natural request. 5. Commit the folder so the team gets it, and delete the moved text from CLAUDE.md. The bundled `/doctor` checkup can propose this migration for you: it looks for always-loaded guidance that could move into skills or nested CLAUDE.md files, and asks before changing anything. ## Neither one is enforcement Both files are instructions the model reads and usually follows. A line in either that says "never edit `.env`" is a request, not a guarantee. What Claude Code lets Claude do is decided by permission rules, permission modes, hooks, the sandbox and managed settings. When a rule must hold every time, put the guarantee in a hook or a deny rule, and keep the explanation of why in CLAUDE.md or the skill.
- Does a skill cost anything in context if nobody ever invokes it?Yes, by default. Each model-invocable skill's name and description sit in the skill listing on every turn so Claude can decide to use it. Only a skill with `disable-model-invocation: true` costs nothing until you type `/name`, because its description is left out of the listing, which also means Claude can no longer load it on its own.
- When would you choose a subagent over a skill for the same playbook?When the work would flood your main conversation, such as reading dozens of files or running long searches. A subagent works in its own context window and returns a summary, while a skill's body is added to your window. They combine: a skill with `context: fork` hands its body to a subagent as the task, and a subagent can preload skills.
- What happens to an invoked skill when the session auto-compacts?Claude Code re-attaches the most recent invocation of each skill after the summary, keeping the first 5,000 tokens of each within a 25,000-token total, filled from the most recently invoked skill. Older skills can drop out entirely, so put the critical instructions at the top of `SKILL.md` and re-invoke the skill if Claude stops following it. CLAUDE.md is simply re-read from disk.
- CLAUDE.md and skills both load in full at session start.
- A skill costs no context at all until someone invokes it.
- Putting a rule in a skill makes Claude Code enforce it.
- Long reference docs belong in CLAUDE.md so Claude never misses them.
- Skills only run when typed as /name; Claude never loads them itself.