Choose between a skill and CLAUDE.md

Learning objective

Choose on-demand skills for task-specific procedures and CLAUDE.md for universal project instructions.

Core idea

Choose the instruction surface by when the information is needed. Universal project guidance belongs in the project’s CLAUDE.md, which supplies persistent context at session startup. A procedure used for one kind of task belongs in a skill whose full body loads when invoked.

Importance is not the deciding criterion. A deployment checklist can be critical without being relevant to every code edit. A short architectural invariant can apply to every task without being a multi-step procedure. Put each where its loading behavior matches its use.

On-demand does not mean user-only or zero context cost. In a regular session, Claude can load a skill automatically when relevant, and available skill descriptions help it identify those matches. The full instructions load when the skill is used. Invocation controls let you change that default deliberately.

How it works

Keep universal guidance at project scope

Claude Code documents ./CLAUDE.md and ./.claude/CLAUDE.md as project instruction locations shared through version control. Use the project file for coding standards, architecture, naming conventions, and build or test commands that guide ordinary work in that repository.

CLAUDE.md files above the working directory load at launch, while subdirectory files load on demand; see 3.1.1 for scopes and 3.1.4 for loading diagnostics. Conventions that apply only to part of the codebase belong in a path-scoped rule rather than a task-procedure skill; see 3.3 for conditional rules.

The file’s guidance is context rather than enforced configuration. It can explain the team’s standards, but a sentence prohibiting an operation does not replace the permission mechanism that blocks it. See 3.2.5 for skill grants and explicit restrictions, and 1.5.3 for policy enforcement more broadly.

Put the task procedure in a skill

Claude Code recommends a skill when you keep pasting the same checklist or multi-step procedure into chat, or when a section of CLAUDE.md has become a procedure rather than a fact. A service-review checklist, a subsystem investigation, and a deployment runbook each have a specific trigger and expected result.

Keep the procedure in .claude/skills/<name>/SKILL.md for team use. The body can include the steps, evidence to consult, and output criteria needed for that task. Supporting files can hold detailed reference material, with the body directing Claude to read it when relevant. See 3.2.1 for distribution and 3.2.2 for the file structure.

This moves the full procedure out of sessions where it is never used. It does not remove the need for a clear description. A skill’s description states what it does and when Claude should use it; the normal skill listing supplies that description so Claude can select the procedure when the request matches.

Choose who initiates the procedure

By default, both you and Claude can invoke a skill. You can type /skill-name, and Claude can load it when relevant to the conversation. This automatic path means “on demand” includes task-driven selection by Claude, not only a developer remembering a slash command.

For a workflow whose timing must be chosen by a person, set disable-model-invocation: true. Anthropic gives actions such as committing or deploying as examples. The skill’s description is then excluded from Claude’s normal listing context, and the full body loads on direct invocation.

For contextual knowledge that is useful to Claude but not meaningful as a user command, set user-invocable: false. Claude can still load it, while it is hidden from the slash menu and cannot run through direct /name invocation. This is the inverse actor choice, not another spelling for manual-only behavior.

Do not put every important skill behind manual invocation by habit. If the procedure should activate whenever a relevant task arises, its description and default invocation behavior are part of the design. Conversely, do not rely on relevance matching when the team explicitly requires the developer to choose when a consequential procedure begins.

Account for what happens after invocation

For an inline skill, the rendered content enters the conversation and stays across later turns. Claude Code does not reload the file on each later turn. Moving a checklist into a skill therefore avoids its full cost before use; it does not automatically unload the body immediately after the task finishes.

A long inline procedure can still occupy context after invocation. If the workflow’s extensive investigation should happen outside the caller’s working context, consider context: fork as covered in 3.2.4. Do not assume that on-demand loading alone isolates file reads or intermediate reasoning.

Write the procedure concisely even when it is conditional. The skill is a way to load relevant instructions at the right time, not a reason to preserve unlimited explanatory material in the body.

Key distinctions and trade-offs

Universal standard versus task procedure: “Service handlers use this directory” can guide many edits. “Review a service change using these checks” is a task with a trigger and result. Their relevance patterns differ even when they concern the same code.

Always-loaded guidance versus enforced policy: CLAUDE.md supplies context. Permissions and blocking hooks enforce execution decisions. Persistent prose does not gain enforcement merely by loading every session.

On-demand body versus zero cost: Available descriptions normally occupy listing context, and an invoked inline body persists. Conditional loading reduces irrelevant startup material; it does not promise no context consumption.

The trade-off is discoverability against instruction volume. A short universal file makes baseline expectations easy to find. A well-described skill makes specialized procedures available without requiring every session to begin with their full text.

Architecture / decision scenario

A developer productivity team has a root CLAUDE.md containing build commands, service layout rules, a weekly review checklist, and a lengthy release procedure. Most sessions change a small handler, yet each session loads the same release instructions.

The team keeps the build commands and service conventions in the project instruction file. It moves the review procedure to .claude/skills/team-review/SKILL.md, with a description that identifies service-change reviews. That skill can use default invocation behavior if the team wants relevant review requests to trigger it automatically.

It moves the release procedure into a separate skill and sets disable-model-invocation: true because a developer must choose its timing. If the team also maintains contextual reference knowledge with no meaningful direct action, user-invocable: false can make that material model-invocable without adding a user command.

The team uses the instruction-loading diagnostics in 3.1.4 to verify the universal file and checks the procedures through their intended invocation routes. It also keeps each skill body concise because an inline invocation remains in conversation context. The result is a loading design tied to actual work rather than a rule that every important paragraph belongs at startup.

Common exam traps

• Putting a rarely used checklist in CLAUDE.md because it is important.
• Assuming skills can load only through a user-entered slash command.
• Treating every nested CLAUDE.md as unconditional startup context.
• Equating on-demand loading with zero listing cost or immediate unloading.
• Confusing manual-only disable-model-invocation with model-only user-invocable.
• Treating universal prose as an enforced permission rule.

What to remember

Keep concise universal project guidance in CLAUDE.md. Put task-specific procedures in skills and choose who should invoke them. Remember that descriptions support selection, inline bodies persist after use, and enforcement belongs to execution controls rather than instruction location.

Knowledge check

References

• Anthropic, How Claude remembers your project
• Anthropic, Extend Claude with skills