Claude Code: CLAUDE.md vs Rules vs Skills

If Claude Code keeps forgetting a project convention, loads too much background information, or repeats a workflow only after you paste the same prompt, the fix may be to put the instruction in the right place. Claude Code offers three useful ways to organize guidance: CLAUDE.md files, project rules in .claude/rules/, and Skills.

The short version: use CLAUDE.md for important context that should be available across ordinary work in a project; use rules to separate guidance by topic or restrict it to matching file paths; use Skills for reusable, task-specific knowledge and procedures that Claude can load when relevant or that you invoke directly. They can work together rather than compete.

The quick decision guide

• CLAUDE.md — project facts and conventions that Claude should know regularly, such as package-manager commands, architecture notes, test commands, and shared coding standards.
• .claude/rules/ — modular instructions that keep the main file focused. Use path-scoped rules when guidance only applies to certain files, such as API validation rules for TypeScript route handlers.
• Skills — reusable playbooks, reference material, or multi-step tasks, such as preparing a release, reviewing a migration, or following a project-specific API workflow.
• Hooks — when you need a configured action to run at a lifecycle event, such as checking a command before execution or running a formatter after an edit. Hooks are different from instructions that Claude interprets.

This division follows the official Claude Code documentation: persistent project context, task-specific Skills, and event-driven hooks solve different problems. The best setup is the smallest one that makes the behavior clear and maintainable.

1. What belongs in CLAUDE.md?

Treat CLAUDE.md as the project's concise briefing. It is useful for information that would otherwise need to be explained repeatedly and that is relevant to many tasks. Examples include the repository's architecture, how to install dependencies, how to run tests, naming conventions, and important implementation constraints.

A practical example

# Project conventions

- Use pnpm for package management.

- Run pnpm test before proposing a change as complete.

- API route handlers live in src/api/handlers/.

- Validate external input at the API boundary.

These are examples, not universal rules. Replace them with facts that are actually true for your repository. A command that does not exist or a path that has moved can make an instruction file less useful than having no instruction at all.

Keep the file focused. Anthropic's current documentation recommends aiming for fewer than 200 lines per CLAUDE.md file, because instructions consume context and long files can make important guidance harder to follow. That is a practical guideline, not a guarantee that every project needs a specific line count.

CLAUDE.md is context for the model, not an enforcement mechanism. If you write “never edit production configuration,” Claude may follow that instruction, but the text itself does not technically block an edit. Use access controls, protected environments, or a properly configured hook for requirements that must be enforced.

2. When to use .claude/rules/

Rules let you split guidance into smaller, named files rather than turning the root CLAUDE.md into a large handbook. A project might keep testing, code style, API design, and security guidance in separate Markdown files under .claude/rules/. This makes each topic easier to review and maintain.

Example project layout

your-project/

├── CLAUDE.md

└── .claude/

    └── rules/

        ├── testing.md

        ├── api-design.md

        └── frontend.md

By default, rules without a paths frontmatter condition apply broadly. You can also scope a rule to files that match particular path patterns. For example, a rule for API handlers could start with this YAML frontmatter:

---

paths:

  - "src/api/**/*.ts"

---

# API implementation rules

- Validate request input before using it.

- Return the project's standard error shape.

Path-scoped rules are helpful when a requirement is relevant only to part of a codebase. A frontend accessibility rule, for instance, need not be injected into every unrelated database migration task. Use specific patterns and test that they match the files you intended.

Do not put every preference into a rule just because the directory exists. If a fact is needed across almost every task, the main CLAUDE.md may be clearer. If a procedure is only needed when performing a particular job, a Skill may be a better fit.

3. When to use a Skill

A Skill packages reusable knowledge or a workflow that is useful for a particular task. Examples include a deployment checklist, a code-review process, a migration playbook, or domain-specific API reference material. Skills can be invoked directly with a slash command, and Claude Code can also select a Skill when its description is relevant to the user's request.

A Skill should explain the situation in which it is useful, the steps to follow, and any checks that define a good result. Keep permanent project facts in CLAUDE.md and link to or move detailed procedures into a Skill when they do not need to be present in every task.

Example: release checklist Skill

• Confirm the working tree and branch are correct.
• Run the project's documented test and build commands.
• Review changed files and look for secrets or generated artifacts.
• Summarize changes, remaining risks, and any steps that were not run.

This is only an example workflow. Adapt the checklist to the repository and release process you actually use. Do not let a Skill assume access to credentials or production permissions that the user has not provided.

If a Skill performs side effects—such as deploying, publishing, or deleting data—consider whether it should be invoked only by you rather than selected automatically. Claude Code supports frontmatter such as disable-model-invocation for controlling model-initiated Skill use; verify the current Skills documentation for the exact supported fields and behavior.

4. Instructions versus automation: when hooks are the better choice

CLAUDE.md, rules, and Skills are instructions that Claude interprets. If you need a specific action to happen at a matching lifecycle event, consider a hook instead. For example, a PostToolUse hook can run a formatter or test command after a relevant tool operation, while a PreToolUse hook can be configured to block a matching action.

Hooks are not a substitute for a thoughtful permission model. Review the event, matcher, handler, failure behavior, and scope before relying on one. Keep server-side or operating-system access controls in place for sensitive resources, and test the hook with both matching and non-matching actions.

A useful rule of thumb is: put explanations and reusable guidance in instruction files; use Skills for task playbooks; use hooks for configured event-driven behavior; use actual permissions and infrastructure controls for security boundaries.

5. A realistic setup for a web application

Imagine a repository containing a React frontend, API routes, and automated tests. You could organize the guidance like this:

• CLAUDE.md: package manager, repository map, setup steps, test commands, and a few project-wide conventions.
• .claude/rules/frontend.md: component conventions and accessibility checks, scoped to frontend files if appropriate.
• .claude/rules/api.md: request validation, authentication checks, and response conventions for API code.
• A Skill named around release preparation: a repeatable checklist for running tests, reviewing the diff, and writing release notes.
• A hook: a deliberately configured formatter or a guard for a narrowly defined risky operation.

This layout reduces repetition without trying to force every kind of guidance into one file. It also gives maintainers a clear place to update a convention, a path-specific rule, or a recurring procedure.

6. Troubleshooting when guidance seems ignored

• Confirm the file is in the expected location and that its name and extension are correct.
• Use Claude Code's documented context or memory inspection commands to confirm which instruction files were loaded.
• Check path patterns in rule frontmatter against the actual file paths; a pattern that does not match will not provide the intended guidance.
• Look for conflicting instructions across user-level, project-level, and nested files. Remove outdated or contradictory guidance.
• Make instructions concrete and testable. “Run pnpm test before finishing” is easier to evaluate than “make sure the code is good.”
• For a Skill, make its description specific about the tasks it handles. If you need to test it directly, invoke it explicitly rather than relying on automatic selection.
• Start a fresh session when needed to confirm that changes to the instruction setup are picked up as documented.

If your Skill is not being selected, see our related guide, Why Your Claude Skill Isn't Triggering. It focuses on the Skill description and selection problem, while this article helps decide where a piece of guidance should live.

7. A checklist before adding another file

• Does this information need to be available for many tasks? Put concise project-wide context in CLAUDE.md.
• Does it apply only to a particular file type or directory? Consider a path-scoped rule.
• Is it a repeatable, multi-step procedure or specialist reference? Consider a Skill.
• Must an action run or be blocked at a particular lifecycle event? Evaluate a hook and test its behavior.
• Is the requirement security-critical? Enforce it with permissions and infrastructure controls, not prose alone.
• Can you delete duplicated or obsolete instructions after reorganizing? Keep the final setup consistent.

Frequently asked questions

Should I put all instructions in CLAUDE.md?

No. Keep CLAUDE.md focused on important context and conventions that are useful across tasks. Use rules to organize specialized guidance and Skills for reusable task-specific procedures.

Do .claude/rules/ files always load?

Rules without path conditions are generally loaded as project guidance. Rules with paths are conditional on matching files. Check the current Claude Code documentation for details about rule loading and configuration sources.

Can a Skill replace a hook?

Not when you need event-driven behavior. A Skill provides instructions for Claude to follow; a hook is configured to execute at a matching lifecycle event. For security-sensitive actions, use appropriate permissions and enforcement controls as well.

Will a shorter CLAUDE.md guarantee better results?

No. Conciseness helps keep guidance focused, but accuracy and relevance matter too. Remove repetition, retain useful project facts, and verify that the instructions match the actual codebase.

Official references

Claude Code: How Claude remembers your project — CLAUDE.md, project instruction placement, and path-scoped rules.

Claude Code: Extend Claude with Skills — Skill structure, invocation, and configuration.

Claude Code: Hooks reference — lifecycle events, matchers, and hook behavior.