Skills vs CLAUDE.md — What Goes Where and Why It Matters
CLAUDE.md is always-on context that shapes every response. Skills are on-demand actions triggered for specific workflows. This article gives you a clear decision framework for choosing between them, with a comparison table and common mistakes to avoid.
Quick Reference
- →CLAUDE.md = passive context loaded automatically every session
- →Skills = active instructions loaded on demand when invoked
- →If it should always influence Claude's behavior, it belongs in CLAUDE.md
- →If it is a specific workflow you trigger manually, it is a skill
- →.claude/rules/ files are a hybrid: conditional context that loads based on file patterns
- →Putting too much in CLAUDE.md wastes context tokens on every message
- →Putting conventions in skills means Claude forgets them when the skill is not active
In this article
The Core Distinction
CLAUDE.md tells Claude who it is working with and what the project looks like. Skills tell Claude to do a specific thing right now.
The confusion between CLAUDE.md and skills is the most common mistake new Claude Code users make. It leads to bloated CLAUDE.md files that waste context, or skills that fail because they lack project context. Understanding the boundary between them is essential for using Claude Code effectively.
| CLAUDE.md | Skills | |
|---|---|---|
| Type | Passive context | Active instructions |
| Loaded | Automatically, every session | On demand, when invoked |
| Purpose | Shape all responses | Execute a specific workflow |
| Analogy | An onboarding doc | A runbook or SOP |
| Grows with | Project conventions | Team workflows |
| Token cost | Paid on every message (always in context) | Paid only when invoked |
| Example | 'We use Tailwind CSS v4' | 'Scaffold a new API endpoint' |
The Decision Framework
When you have a new piece of information or instruction for Claude Code, ask yourself these three questions to determine where it belongs.
Is it always relevant?
If yes, it belongs in CLAUDE.md. Examples: tech stack, naming conventions, directory structure, coding standards. These influence every response Claude generates.
Is it a specific action triggered on demand?
If yes, it is a skill. Examples: generating commit messages, scaffolding components, running security audits, writing PR descriptions.
Is it context that is only relevant for certain files?
If yes, it belongs in .claude/rules/ with a glob pattern. Examples: React component conventions (only when editing .tsx files), database rules (only when editing data layer files).
If you would want Claude to know this on every single message, it is CLAUDE.md. If you would only want it 10% of the time for a specific task, it is a skill. If it depends on which files you are editing, it is .claude/rules/.
Concrete Examples
Let us walk through real scenarios and determine where each piece of information belongs.
| Information / Instruction | Where It Goes | Why |
|---|---|---|
| We use Next.js 15 with App Router | CLAUDE.md | Influences every file Claude writes — routing, imports, patterns |
| Generate a commit message following Conventional Commits | Skill | On-demand action triggered before committing |
| React components must use forwardRef for DOM wrappers | .claude/rules/ | Only relevant when editing component files |
| Prefer named exports over default exports | CLAUDE.md | Affects every file Claude creates |
| Scaffold a new API endpoint with Zod validation and tests | Skill | On-demand scaffolding action |
| Database queries must use Prisma, not raw SQL | .claude/rules/ | Only relevant when editing data layer files |
| Run a security-focused code review | Skill | On-demand review action |
| Our test files live next to source files (Button.test.tsx) | CLAUDE.md | Affects test file creation in every part of the codebase |
The Hybrid Zone: .claude/rules/
The .claude/rules/ directory occupies a middle ground. Like CLAUDE.md, rules provide passive context. But like skills, they are conditional — they only load when you are working on matching files. This makes them perfect for domain-specific conventions that would waste context if loaded globally.
| Mechanism | When It Loads | Best For |
|---|---|---|
| CLAUDE.md | Always | Universal conventions (tech stack, naming, structure) |
| .claude/rules/ | When editing matching files | Domain-specific conventions (API rules, component rules) |
| Skills | When explicitly invoked | On-demand workflows (scaffolding, reviewing, generating) |
Common Mistakes
These are the mistakes I see most often when teams configure Claude Code. Each one degrades the quality of Claude's output.
Putting 'When I ask you to review code, check for security issues, performance problems, and style violations' in CLAUDE.md means those instructions consume context tokens on every single message — even when you are just asking Claude to rename a variable. Move workflow instructions to skills.
A skill that says 'Use named exports and Tailwind CSS v4' only applies when the skill is active. When Claude writes code without that skill invoked, it will not follow those conventions. Universal conventions must live in CLAUDE.md.
Teams dump everything into CLAUDE.md because they do not know about conditional rules. A 500-line CLAUDE.md full of domain-specific rules wastes context. Move domain rules to .claude/rules/ with appropriate glob patterns.
If your skill repeats instructions that are already in CLAUDE.md, you are wasting tokens and creating a maintenance burden. Skills should reference CLAUDE.md conventions, not duplicate them.
Migrating a Bloated CLAUDE.md
If your CLAUDE.md has grown unwieldy, here is how to split it into the right pieces.
Audit every section
Read each section of your CLAUDE.md and ask: does this need to be in every conversation? If not, it should move.
Extract domain rules
Move domain-specific conventions (API rules, component rules, database rules) into .claude/rules/ files with appropriate glob patterns.
Extract workflows into skills
Any instruction that starts with 'When I ask you to...' or describes a multi-step process should become a skill.
Keep the core
What remains in CLAUDE.md should be: tech stack, universal conventions, directory structure, and project-wide constraints.
Verify context savings
Use /status to check context usage before and after the migration. You should see a meaningful reduction.
Cheat Sheet
| Question | Answer |
|---|---|
| Where does the tech stack go? | CLAUDE.md |
| Where does the commit message format go? | Skill (on-demand workflow) |
| Where do React component rules go? | .claude/rules/ with tsx glob |
| Where does the directory structure go? | CLAUDE.md |
| Where does the code review checklist go? | Skill (on-demand workflow) |
| Where do security constraints go? | CLAUDE.md (universal) or .claude/rules/ (file-specific) |
| Where does the PR template go? | Skill (on-demand workflow) |
| Where does 'prefer named exports' go? | CLAUDE.md (universal convention) |
Best Practices
Do
- ✓Use the frequency test: always relevant = CLAUDE.md, sometimes relevant = .claude/rules/, on demand = skill
- ✓Keep CLAUDE.md lean — only universal, always-on context belongs there
- ✓Use .claude/rules/ for domain-specific conventions with appropriate glob patterns
- ✓Design skills to reference CLAUDE.md conventions rather than duplicating them
- ✓Audit your CLAUDE.md periodically and extract sections that have become domain-specific
Don’t
- ✗Don't put workflow instructions in CLAUDE.md — they waste context tokens on every message
- ✗Don't put universal conventions in skills — they are lost when the skill is not active
- ✗Don't ignore .claude/rules/ — it solves the 'sometimes relevant' problem elegantly
- ✗Don't duplicate the same information across CLAUDE.md and skills
- ✗Don't let CLAUDE.md grow unbounded — if it exceeds a few hundred lines, split it
Key Takeaways
- ✓CLAUDE.md is always-on passive context; skills are on-demand active instructions
- ✓.claude/rules/ is the hybrid: conditional context loaded based on file patterns
- ✓The frequency test determines where information belongs: always, sometimes, or on demand
- ✓Putting workflows in CLAUDE.md wastes context; putting conventions in skills loses them
- ✓A well-organized Claude Code setup uses all three mechanisms together
Video on this topic
Skills vs CLAUDE.md in 60 Seconds
tiktok