CLAUDE.md vs SKILL.md: When to Use Each in Claude Code

If you are new to Claude Code, this is one of the first confusions you hit:

Should this go in CLAUDE.md, or should it be a skill in SKILL.md?

They are related, but they do different jobs.

CLAUDE.md is for persistent instructions and context that Claude should carry into sessions automatically. SKILL.md is for reusable, task-specific capabilities that Claude can invoke when relevant or that you can call directly with /skill-name.

That distinction sounds simple, but in practice people blur the line all the time. They dump workflows into CLAUDE.md, or they create skills for rules that should have lived in project memory from the start. The result is noise, missed invocations, and a setup that feels smarter in theory than it is in daily use.

This guide gives you the practical framework.

If you want the deeper hands-on walkthrough for skill files themselves, read the companion guide first or right after this one: Claude Code Skills: A Practical Guide to Writing SKILL.md Files.

Contents

1. The short answer
2. What CLAUDE.md is for
3. What SKILL.md is for
4. The real difference: always-on context vs on-demand capability
5. When to use CLAUDE.md
6. When to use SKILL.md
7. A practical decision framework
8. The fast rule I use
9. Examples side by side
10. Why beginners misuse CLAUDE.md
11. Why beginners misuse skills
12. Where hooks fit in
13. Where settings fit in
14. A simple file-organization pattern that works
15. My practical recommendation
16. A bad setup vs a good one
17. The most important rule

1. The short answer

Use CLAUDE.md for things that should be true almost all the time in a project or workflow.

Use SKILL.md for things that should be loaded only when relevant or run as a reusable workflow.

That is the core rule.

2. What CLAUDE.md is for

Anthropic describes CLAUDE.md as a way to give Claude persistent instructions for a project, your user profile, or your organization. Claude reads these files at the start of sessions, and more specific files take precedence over broader ones. Claude can also load subdirectory CLAUDE.md files on demand when it enters those parts of the codebase.

So CLAUDE.md is where you put things like:

• project architecture notes
• coding conventions
• team norms
• standard build and test commands
• recurring repo-specific constraints
• "how we do things here"

Examples:

# CLAUDE.md

- Use pnpm, not npm.
- Run `pnpm test` before making code changes final.
- In this repo, API handlers live in `src/server/routes/`.
- Do not touch `legacy/payments/` without reading `docs/payment-migration.md`.
- Prefer small, focused diffs over broad refactors.

That is a good CLAUDE.md shape because those instructions apply broadly and repeatedly.

Anthropic's memory docs explicitly position CLAUDE.md for instructions and rules, including project architecture and coding standards.

3. What SKILL.md is for

Skills extend Claude Code with custom capabilities. A SKILL.md file adds a skill that Claude can use when relevant, or that you can invoke directly via /skill-name.

A skill is not just "more instructions." It is closer to a packaged workflow.

Examples:

• review a PR for security and performance issues
• generate docs from a set of handlers
• deploy to staging
• run a migration checklist
• work a GitHub issue from issue number
• produce a changelog from git history

That is why skills have frontmatter like description, allowed-tools, argument-hint, and optional invocation controls. Skills should be concise, structured, discoverable, and designed around real use.

A basic example:

---
name: review
description: Review a pull request or recent code changes for security issues, performance problems, and style violations
allowed-tools: Read, Grep, Glob
---

Review the code in $ARGUMENTS or the most recent changes.

Check for:
- security issues
- performance problems
- correctness bugs
- style violations

Give file and line references.
Separate must-fix issues from suggestions.

That belongs in a skill, not in CLAUDE.md.

Why? Because it is not a standing project rule. It is a reusable task.

4. The real difference: always-on context vs on-demand capability

This is the cleanest mental model:

• CLAUDE.md = always-on memory/context
• SKILL.md = on-demand capability/workflow

CLAUDE.md tells Claude:

"This is how this project works."

A skill tells Claude:

"When this kind of task comes up, use this procedure."

CLAUDE.md files are memory files loaded as instructions/context, while skills are custom prompts that can be invoked manually or automatically when relevant.

5. When to use CLAUDE.md

Use CLAUDE.md when the information should shape many or most interactions in the repo.

1. Coding standards

Things like naming, formatting, test expectations, file organization.

2. Architecture and boundaries

Where core systems live, which modules are legacy, which folders are sensitive.

3. Team workflow defaults

Preferred commands, review expectations, branch conventions.

4. Standing constraints

• "Never edit generated files directly."
• "Use service layer X for database access."
• "Do not introduce a new queue without team approval."

5. Persistent user preferences

At the user-level ~/.claude/CLAUDE.md, personal preferences that apply across projects.

Examples that belong in CLAUDE.md:

• "Use ripgrep instead of grep in this repo."
• "Frontend tests use Vitest, not Jest."
• "Prefer minimal patches."
• "Do not rename exported APIs without updating the public docs."
• "Always inspect existing patterns before inventing a new abstraction."

These are not one-off tasks. They are standing guidance.

6. When to use SKILL.md

Use a skill when the instructions are only relevant for a specific class of task.

1. Multi-step workflows

A checklist or sequence that Claude should follow reliably.

2. Slash-command-worthy tasks

If you naturally imagine calling /review, /deploy, /fix-issue, /gen-docs, it probably wants to be a skill.

3. Tasks with their own tool permissions

Skills can declare allowed-tools, which is a strong hint that they are operational units rather than passive memory.

4. Tasks that take arguments

If you need $ARGUMENTS, $0, $1, that usually points to a skill.

5. Things that should not clutter every session

If it is only useful occasionally, keep it out of CLAUDE.md.

Examples that belong in SKILL.md:

• PR review workflow
• deployment process
• changelog generation
• issue triage
• migration checklist
• API docs generation
• release-note drafting

For actual examples of skill shapes, the companion guide goes much deeper.

7. A practical decision framework

When deciding between the two, ask these five questions.

1. Does this apply to almost every session?

If yes → use CLAUDE.md. If no → keep going.

2. Is this a reusable task or procedure?

If yes → use SKILL.md.

3. Would I ever want to invoke this as a command?

If yes → use SKILL.md.

4. Would loading this all the time waste context and attention?

If yes → use SKILL.md.

5. Is this guidance about the repo itself rather than a workflow?

If yes → use CLAUDE.md.

That gets you to the right answer most of the time.

8. The fast rule I use

Here is the blunt version:

Put rules in CLAUDE.md

Put routines in SKILL.md

Rules are persistent. Routines are invoked.

9. Examples side by side

Example 1: Testing conventions

This belongs in CLAUDE.md:

- Run `pnpm test` for affected packages before finalizing work.
- For backend changes, also run `pnpm test:api`.
- Do not add snapshot tests for API responses.

Why: these are standing repo norms.

Example 2: Generate a release changelog

This belongs in SKILL.md:

---
name: changelog
description: Generate a release changelog from git history for a version range or recent commits
allowed-tools: Bash(git log *), Bash(git show *)
argument-hint: "[from-ref]..[to-ref]"
---

Generate a markdown changelog for $ARGUMENTS.
Group entries into features, fixes, and internal changes.
Skip pure maintenance commits.

Why: specific workflow, specific tools, specific invocation.

Example 3: Legacy payments warning

This could go in CLAUDE.md if it is broadly important:

- Avoid refactoring `src/payments/legacy/` without reading `docs/payments-legacy.md`.
- This module still depends on an old provider flow.

Why: standing architectural warning that applies across all sessions.

But if you had a special troubleshooting or migration procedure for that legacy area, that should become a skill.

Example 4: PR review with a checklist

This should be a skill. Skills are designed exactly for this sort of reusable instruction bundle.

10. Why beginners misuse CLAUDE.md

Because CLAUDE.md feels easy.

You open one file and dump everything into it: coding rules, deployment steps, review process, onboarding notes, bug triage, docs generation, architecture notes, commit style, shell recipes.

That works at first, then it rots.

Why? Because CLAUDE.md is loaded as session context, and Claude treats it as context rather than hard enforcement. If you keep stuffing operational procedures into it, you make the baseline context heavier and less clean.

The problem is not just size. It is signal dilution.

Your truly important repo instructions get buried among workflows that should have been skills.

11. Why beginners misuse skills

The opposite mistake is turning every tiny preference into a skill.

Bad examples:

• a skill just to remind Claude to write concise code
• a skill just to prefer TypeScript
• a skill just to use one folder convention
• a skill just to say "run tests"

That is not what skills are for. Skills should be concise, structured, and built around real repeatable use. A micro-skill for a standing project convention is usually the wrong abstraction.

If a rule is always relevant, it belongs in CLAUDE.md.

12. Where hooks fit in

Hooks are another source of confusion.

Hooks are not the same as either CLAUDE.md or skills. Hooks are automatic commands, HTTP endpoints, or LLM prompts that run at specific points in Claude Code's lifecycle, providing deterministic control and enforcement.

So the rough split is:

That matters because some things people try to force into CLAUDE.md should really be hooks.

Example: "Always format code after edits."

That is often better as a hook than as a memory instruction, because hooks are deterministic and do not depend on Claude remembering to do it. Hooks ensure certain actions always happen instead of relying on the model to choose to run them.

So if you are trying to decide between CLAUDE.md and SKILL.md, sometimes the real answer is: neither — use a hook.

13. Where settings fit in

Settings files are for configuration like permissions, environment variables, and tool behavior — they are not a substitute for CLAUDE.md or skills.

That means:

• do not put tool permissions in CLAUDE.md
• do not use skills to replace actual config
• do not confuse project instructions with runtime settings

Each layer has its job.

14. A simple file-organization pattern that works

For a normal project, this is a solid setup:

CLAUDE.md — keep this short and opinionated:

• architecture
• coding standards
• repo-specific rules
• default commands
• "don't break this" notes

.claude/skills/ — put reusable workflows here:

• review
• deploy
• changelog
• fix-issue
• docs generation
• migration helpers

hooks — use for automatic formatting, validation, notifications, command blocking, or other deterministic behavior.

That division is clean and scales.

15. My practical recommendation

If you are starting from scratch:

Put in CLAUDE.md:

• project overview
• architecture map
• test/build commands
• style rules
• dangerous areas
• non-negotiable constraints

Turn into skills:

• review workflows
• deployment workflows
• issue workflows
• migration playbooks
• docs generation
• release tasks
• repetitive investigation tasks

Use hooks for:

• mandatory formatting
• guardrails
• notifications
• lifecycle automation

That gives you the least messy setup.

16. A bad setup vs a good one

Bad: one giant CLAUDE.md containing standards, build steps, release process, review checklist, PR template, docs generation flow, deployment instructions, rollback instructions, and issue handling flow.

That is lazy architecture and it degrades fast.

Good: a focused CLAUDE.md with standing rules, plus skills for each reusable workflow, plus hooks for deterministic automation.

That setup matches how Anthropic separates memory, skills, hooks, and settings in the product docs.

17. The most important rule

Ask this:

Should Claude remember this all the time, or only when a certain task comes up?

If it should remember it all the time → use CLAUDE.md.

If it should load it only for a specific task → use SKILL.md.

That is the real answer.

CLAUDE.md and SKILL.md are not competing features. They solve different problems.

Use CLAUDE.md to define the persistent shape of the project: standards, architecture, defaults, and standing instructions.

Use SKILL.md to package reusable workflows that Claude can invoke directly or load when relevant.

If you keep that split clean, Claude Code becomes much more predictable.

And if you want the deeper practical guide to actually authoring good skills, examples, frontmatter decisions, and common mistakes, read the companion article: Claude Code Skills: A Practical Guide to Writing SKILL.md Files.

Keywords

CLAUDE.md vs SKILL.md, Claude Code memory files, Claude Code skills, when to use CLAUDE.md, when to use SKILL.md, Claude Code project instructions, Claude Code custom skills, CLAUDE.md best practices, SKILL.md guide, Claude Code hooks, Claude Code workflow, Claude Code team setup, Claude Code persistent instructions, Claude Code slash commands, AI developer tools configuration