What is the difference between a rule and a skill?

A rule is a convention Claude should know whenever it touches matching files, and it loads automatically on a path match. A skill is a procedure Claude runs occasionally, and it loads only when invoked or judged relevant.

How do I scope a rule to specific files?

Add YAML frontmatter with a paths field listing glob patterns, such as src/api/**/*.ts or src/**/*.{ts,tsx}. A rule with no paths field applies to everything and loads at launch.

Project rules go in .claude/rules/ as one markdown file per topic, discovered recursively so you can nest them in subdirectories. Personal rules for every project go in ~/.claude/rules/ and load before project rules.

Does splitting my CLAUDE.md actually save context?

Only if you split into path-scoped rules or skills. Those load on demand. Splitting into @path imports does not save anything, because imported files are expanded into context at launch.

Agent instruction guide

CLAUDE.md vs .claude/rules vs Skills — Which File Owns What

Route each instruction to the right file: always-loaded CLAUDE.md, path-scoped .claude/rules/, or on-demand skills. One question decides it.

Direct answer

One question routes every instruction: when does this need to be in context? Always, for every task — CLAUDE.md, which loads in full at the start of every session. Only when Claude touches certain files — a rule in .claude/rules/ with a paths frontmatter field, which loads when Claude reads a matching file. Only when a specific task comes up — a skill, which loads when you invoke it or when Claude judges it relevant. Moving procedures out of CLAUDE.md into rules and skills is the main way to shrink an oversized file without losing the content.

Open CLAUDE.md Reviewer

When to use this

Your CLAUDE.md is over 200 lines and you need to split it, not delete it.
You have testing rules that only matter when Claude edits test files.
You have a release or review procedure sitting in CLAUDE.md that runs once a month.

Steps

Paste your CLAUDE.md into the reviewer and note which sections are procedures rather than facts.
Keep in CLAUDE.md: commands, conventions, layout, and always-true rules.
Move file-type guidance into .claude/rules/<topic>.md with a paths field, such as paths: ['src/api/**/*.ts'].
Move multi-step procedures into skills, which load only when relevant.
Run /context in a session and confirm the split file set still loads what you expect.

Example review focus

CLAUDE.md excerpt

# CLAUDE.md

## Testing
- Test files use Vitest and live beside the source file.
- Mock network calls with msw, never real fetch.

## Release
1. Bump the version in package.json.
2. Run npm run build.
3. Tag the commit.
4. Push the tag.
5. Verify the GitHub Action went green.
6. Announce in #releases.

## Commands
- npm run dev
- npm run test

What to fix

Keep the Commands section in CLAUDE.md. Move Testing into .claude/rules/testing.md with paths: ['**/*.test.ts'] so it loads only when Claude opens a test file. Move Release into a skill: it is a six-step procedure that runs once per release and does not belong in every session's context.

Common mistakes

Do not use rules without a paths field to save context; those load at launch just like CLAUDE.md.
Do not use @path imports as a size fix; imports are organization only, and the content still loads at launch.
Do not duplicate a rule in both CLAUDE.md and .claude/rules/; duplicates become contradictions when one is edited.
Do not expect a path-scoped rule to survive /compact; it reloads the next time Claude reads a matching file.

FAQ

What is the difference between a rule and a skill?: A rule is a convention Claude should know whenever it touches matching files, and it loads automatically on a path match. A skill is a procedure Claude runs occasionally, and it loads only when invoked or judged relevant.
How do I scope a rule to specific files?: Add YAML frontmatter with a paths field listing glob patterns, such as src/api/**/*.ts or src/**/*.{ts,tsx}. A rule with no paths field applies to everything and loads at launch.
Where do rules live?: Project rules go in .claude/rules/ as one markdown file per topic, discovered recursively so you can nest them in subdirectories. Personal rules for every project go in ~/.claude/rules/ and load before project rules.
Does splitting my CLAUDE.md actually save context?: Only if you split into path-scoped rules or skills. Those load on demand. Splitting into @path imports does not save anything, because imported files are expanded into context at launch.

Related CLAUDE.md guides

Review CLAUDE.md for Token Waste

Find vague, repeated, or unused CLAUDE.md instructions that cost tokens every Claude Code turn without improving behavior.

CLAUDE.md Missing Commands Checklist

Check whether a CLAUDE.md includes the build, test, lint, dev server, deploy, and verification commands an agent needs before editing.

CLAUDE.md Repo Boundaries and Rules

Write CLAUDE.md rules that tell agents which files to edit, which files to avoid, and how to handle dirty worktrees safely.

Review CLAUDE.md Before Converting to AGENTS.md

Clean a CLAUDE.md first, then convert it into AGENTS.md, Cursor rules, GitHub Copilot instructions, or Windsurf rules.

What Should Go in a CLAUDE.md File

Decide what belongs in CLAUDE.md and what belongs in the README, a path-scoped rule, or a skill. One test per line, applied to a real file.

Claude Code Is Not Following CLAUDE.md — How to Fix It

Diagnose why Claude Code ignores your CLAUDE.md: the file never loaded, the rule is vague, two files contradict, or the rule needs a hook instead.

CLAUDE.md Best Practices Checklist — Audit Your File Against 8 Rules

Run your CLAUDE.md through eight checks: size, specificity, exact commands, anti-patterns, structure, contradictions, enforcement, and staleness.

Desk gear for long writing sessions

A few things that help if you write docs, tickets, and specs on a laptop all day.

Dock

Anker 5-in-1 USB-C Hub

One cable turns a laptop into a desk setup. Drives a 4K display, charges at up to 85W, and adds three data ports.

4K HDMI output
85W max power delivery
1x USB-C + 2x USB-A, 5Gbps each
MacBook Pro, MacBook Air, Dell

Check price on Amazon →Monitor · I use this

Dell 27" S2725QC 4K

The monitor I write and review documents on. 163 PPI keeps small text sharp, and USB-C carries video and power on one cable.

3840x2160 IPS, 163 PPI
120Hz, 4ms, FreeSync Premium
99% sRGB
USB-C, HDMI, DisplayPort

Check price on Amazon →Laptop

Apple MacBook Neo 13" (A18 Pro)

The cheapest way into an Apple-silicon machine that runs local models. Fanless, and the Liquid Retina panel holds small text at a full day of reading.

A18 Pro chip, built for Apple Intelligence
8GB unified memory, 256GB SSD
13-inch Liquid Retina display
1080p FaceTime HD camera

Check price on Amazon →

Amazon affiliate links. We earn a commission on qualifying purchases at no extra cost to you.