title: "When Should I Use a Skill Instead of Writing Instructions in CLAUDE.md?" description: "CLAUDE.md is always-on context. Skills are on-demand processes. Here is the exact decision rule for deciding which one holds your Claude Code instructions." pubDate: "2026-04-13" category: skills tags: ["claude-code-skills", "claude-md", "skill-vs-claude-md"] cluster: 2 cluster_name: "Skills vs Agents vs Prompts" difficulty: beginner source_question: "When should I use a skill instead of writing instructions in CLAUDE.md?" source_ref: "2.Beginner.3" word_count: 1390 status: draft reviewed: false schema_types: ["Article", "FAQPage"]

When Should I Use a Skill Instead of Writing Instructions in CLAUDE.md?

Quick answer: Put instructions in CLAUDE.md when they apply to every session with no trigger. Build a skill when the instructions apply only to a specific, repeatable task invoked by name. CLAUDE.md is always-on. Skills are on-demand. That single distinction covers 90% of the decision.

CLAUDE.md is the right place for:

• Project rules
• Naming conventions
• Tech stack context

What Does CLAUDE.md Do?

CLAUDE.md is a context file Claude reads automatically at the start of every session. It gives Claude the standing information it needs to work in your project:

• Tech stack
• Folder structure
• Naming conventions
• Team protocols
• Any constraints that apply to all work in this codebase

CLAUDE.md is appropriate for:

• Project context Claude needs before it can understand your codebase
• Rules that apply to every task in the project (always use TypeScript, never commit to main directly)
• Short descriptions of the team's workflow and standards
• Pointers to key files and their roles

The cost of CLAUDE.md is that it loads on every session, whether relevant or not. A 300-line CLAUDE.md file means Claude carries 300 lines of context even when you are running a task where none of it applies, a commit message skill that has no use for your deployment environment variables or your release changelog format (Source: Claude Code context window management, 2026). Claude Code's default context window is 200,000 tokens; CLAUDE.md competes directly with code and conversation for that budget (Source: Anthropic Claude technical documentation, 2026). In practice, most CLAUDE.md files that have been in use for more than a few months contain the majority of their line count in workflow instructions that would be better placed in skills.

What Does a Claude Code Skill Do?

A Claude Code skill is a SKILL.md file that defines one specific, triggerable task. You invoke it by name: /commit, /review-pr, /release-notes. Claude loads the full skill only when you trigger it. Between invocations, it costs roughly 100 tokens at startup for the skill metadata and nothing more (Source: Claude Code context window architecture, 2026).

Skills are appropriate for:

• Repeatable processes with a defined trigger (/commit, /review-pr, /deploy)
• Instructions too detailed to embed in CLAUDE.md without crowding out other context
• Domain expertise that applies only to specific workflow phases, not to the entire project
• Team workflows where you want consistent execution across multiple developers

The difference from CLAUDE.md is specificity and cost. A skill is scoped to one task. It loads on demand. CLAUDE.md is scoped to the whole project and loads always. Teams that migrate workflow blocks to skills typically reduce their CLAUDE.md size substantially while keeping the same effective instruction coverage.

How Do You Know Which One to Use?

If the instruction should always be active across every Claude session, it belongs in CLAUDE.md. If it only applies when a specific named task is running, it belongs in a skill. Two diagnostic questions make this concrete for any instruction you are deciding about.

Ask two questions:

1. Should this instruction always be active, or only when a specific task is running?

Always active: CLAUDE.md. Only during a specific task: Skill.

2. Would loading this instruction in every session help or create noise?

Helps every session: CLAUDE.md. Only needed for one workflow: Skill.

"Frontier LLMs can follow approximately 150–200 instructions with reasonable consistency. Beyond that, compliance degrades." — Kyle, HumanLayer (November 2025, https://www.humanlayer.dev/blog/writing-a-good-claude-md)

The canonical examples:

The pattern: CLAUDE.md holds facts and standing rules. Skills hold processes and workflows.

What Are the Signs You Have Put the Wrong Thing in CLAUDE.md?

The clearest signs are sections that only fire for one task, step-by-step process blocks, instructions you scroll past to find today's work, and a file over 200 lines. Any one of these means workflow content has crept into what should be permanent project context.

CLAUDE.md becomes a problem when it turns into a workflow dump.

The warning signs:

• Sections that only apply to one specific task. If a block of CLAUDE.md only applies when you are running releases, it belongs in a /release skill, not in CLAUDE.md.
• Instructions you skip past to find what you need. If you scroll past multiple sections to find the context relevant to today's work, those skipped sections are adding noise without value.
• Step-by-step processes. CLAUDE.md is not a workflow file. Numbered steps in CLAUDE.md for how to run a specific task are skill candidates.
• File length over 200 lines. CLAUDE.md over 200 lines begins to dilute Claude's attention on the project context that actually matters. Each additional line makes every other line slightly less reliable.

Some teams hit 400 lines in CLAUDE.md before realizing the problem. At that point, the file reads like a project wiki, and Claude is carrying 400 lines of context on every session whether needed or not. Moving workflow sections to skills brings the file back to its actual function: permanent project context.

In AEM's production skill builds, we've found that extracting workflow sections from CLAUDE.md into named skills consistently produces a smaller, more reliable project context file — and the extracted skills become easier to test and iterate on independently than embedded CLAUDE.md blocks ever were.

How Do You Move Instructions from CLAUDE.md to a Skill?

Identify workflow blocks in CLAUDE.md, create a named skill for each one, then replace the original block with a single-line pointer. The full instructions live in the skill; CLAUDE.md keeps only the reference. Most migrations take under ten minutes per section.

The migration follows three steps:

1. Identify workflow sections in CLAUDE.md. These are blocks with step-by-step instructions, process descriptions, or task-specific rules. Project facts and standing rules stay in CLAUDE.md.

2. For each workflow section, create a skill. Give it a name that matches how you already invoke the workflow (/commit, /review, /deploy). Copy the instructions into the skill's process steps. Add a YAML frontmatter header with name, description, and trigger.

3. Replace the CLAUDE.md section with a one-line pointer. For commit messages, use /commit. The reference is enough. The full instructions now live in the skill.

The result: CLAUDE.md holds context, not workflows. Skills hold workflows, triggered on demand.

For details on what each section of a skill file should contain, see What Goes in a SKILL.md File?.

For the full decision framework across all Claude Code tools, see Claude Code Skills vs Agents vs Prompts: When to Use Which.

FAQ

Should I put my instructions in CLAUDE.md or create a separate skill?

Put instructions in CLAUDE.md when they apply to every Claude Code session in the project. Create a separate skill when the instructions apply to a specific, named, triggerable workflow. The test: would loading these instructions during an unrelated task be helpful or create noise? If noise, it belongs in a skill.

If I find myself copying the same instructions across projects, should that become a skill?

Yes. If the same instructions appear in multiple CLAUDE.md files or are copy-pasted into multiple projects, the instructions belong in a user-level skill installed at ~/.claude/skills/. User-level skills are available across all projects without any per-project configuration. The copy-paste cycle is the signal that it should be a persistent, named skill.

How do I prevent my CLAUDE.md from getting too long?

Move workflow instructions to skills. Remove context that is already obvious from the code or documented elsewhere. Keep CLAUDE.md focused on: tech stack summary, folder structure, team conventions, and any non-obvious constraints. Aim for under 150 lines. A shorter, precise CLAUDE.md is more reliably read than a long one. Claude's attention is finite, and every line competes with every other line.

What's the difference between CLAUDE.md instructions and SKILL.md instructions?

CLAUDE.md instructions are always-on context: project facts, standing rules, permanent constraints. SKILL.md instructions are on-demand process definitions: step-by-step workflows triggered by name. CLAUDE.md tells Claude what is always true about the project. SKILL.md tells Claude exactly how to run a specific task when asked.

Can CLAUDE.md and skills conflict with each other?

Yes. If CLAUDE.md contains a rule that contradicts a skill's process instructions, Claude will attempt to reconcile them with unpredictable results. The fix is to make CLAUDE.md and skills non-overlapping: CLAUDE.md holds standing rules that apply everywhere, and skills hold task-specific instructions that override or complement those rules only when invoked.

Last updated: 2026-04-13