skip to content

Design & Evaluation

Making skills fire when they should: tight descriptions, a listing budget that drops the least-used ones, and with-and-without evals. Asked because skills that never or always trigger are common.

part ofClaude Coderead it →
on this pageshow

explore

questions

6

In Claude Code, when should an instruction live in a skill rather than in CLAUDE.md?

level: juniorimportance: must knowfreq 30%

answer

  1. load timing differs
  2. every session versus on demand
  3. a procedure, not a fact
  4. the description still sits in the listing
  5. both are guidance, not enforcement

basics

~20 s

CLAUDE.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

for a junior

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.

for a middle

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.

for a senior

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.

for a principal

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.
open as a page

In Claude Code, how do you write a skill's description so Claude loads the skill on the requests it should, and only those?

level: middleimportance: must knowfreq 22%

basics

~20 s

Lead the description with what the skill does and when to use it, in the words users actually type; Claude matches requests against the listed description plus when_to_use, cut at 1,536 characters by default, never against the body.

open as a page

A Claude Code skill says to run a spec check after each edit, yet Claude does it once — fix the skill or add a hook?

level: middleimportance: should knowfreq 14%

basics

~20 s

If the check must run after every edit, use a hook: a skill is read once and applied with judgement, while a hook fires on its event every time. Rewording the skill suits judgement calls only.

open as a page

A Claude Code team has forty skills and some never fire despite good descriptions — what is the skill listing budget doing, and how do you fix it?

level: seniorimportance: should knowfreq 9%

basics

~20 s

Claude Code caps the skill listing at 1% of the context window by default; when forty skills overflow it, every name stays but the least-used skills lose their descriptions, so Claude is less likely to pick them. Prune, set name-only, or raise skillListingBudgetFraction.

open as a page

Before adopting a shared Claude Code skill into your project's .claude/skills, what do you review in its folder, and why?

level: seniorimportance: should knowfreq 7%

basics

~20 s

Read it as code that can run: its allowed-tools grants, injected shell commands that execute while it renders, hooks that persist all session, bundled scripts, where and on what model it runs, its name, and whether a side-effecting skill sets disable-model-invocation.

open as a page

How do you prove a Claude Code skill improves results, not just that it triggers, before rolling it out to a team?

level: seniorimportance: nice to knowfreq 6%

basics

~20 s

Run the same realistic prompts in fresh sessions with the skill and without it, then compare whether it fired and whether the output improved; the skill-creator plugin automates this for one skill, and claude plugin eval reports the delta for plugin skills.

open as a page