Once a team starts using Claude Code every day, the same problem shows up.
A developer gives Claude a useful instruction. It works. The next developer copies it. Someone eventually adds it to CLAUDE.md so nobody has to repeat it.
That sounds sensible until the file starts filling up with everything the team has ever asked Claude to do.
Project coding standards are mixed with pull-request checklists. Deployment procedures sit next to debugging instructions. A security review prompt that matters once a week is loaded into conversations that have nothing to do with security.
The result is not necessarily wrong. It is just poorly scoped.
Claude Code gives you several ways to shape its behavior- CLAUDE.md, Skills, custom commands, subagents, and Plan Mode. The useful question is not which feature is best. It is what kind of behavior you are trying to define.
This article looks at that distinction and uses a concrete example — a reusable code-review workflow — to show where each mechanism fits.
I think of CLAUDE.md as project context.
Anthropic documents it as the place for persistent instructions such as coding conventions, project architecture, build and test commands, and other information you would otherwise have to explain repeatedly. These instructions are loaded into the relevant Claude Code sessions.
For example
Use the repository logging module instead of console.log.
Follow the existing transaction-handling pattern.
Run the relevant tests after modifying application code.
Those instructions make sense in a feature-development session, a refactoring session, or a debugging session.
A useful test is this
Would I be annoyed if Claude didn’t know this on every relevant task in this repository?
If the answer is yes, CLAUDE.md is probably the right place.
There is one important caveat. CLAUDE.md is guidance, not a hard enforcement layer. Anthropic explicitly distinguishes it from ** permissions and hooks.** A sentence saying "never do X" influences Claude, but it does not create a technical block on X.
Now consider a team with an eight-point pull-request checklist
API changes
Test coverage
Documentation
Security
Error handling
Performance
Backward compatibility
Maintainability
Developers currently paste this checklist whenever they review a pull request.
This is exactly the kind of thing that starts as a prompt and eventually deserves to become a reusable capability.
Current Claude Code documentation describes Skills for this purpose: reusable capabilities that can contain instructions and supporting files. A Skill can be invoked directly with /skill-name, and Claude can also load it automatically when its description matches the task. Anthropic specifically recommends Skills when you keep pasting the same instructions, checklist, or multi-step procedure into chat.
So the workflow could simply become
/review
The review instructions live with that capability instead of becoming part of every conversation.
That is a subtle but important difference.
CLAUDE.md says
This is how our project generally works.
A review Skill says
This is how we perform a review.
If you’ve learned Claude Code from older material, you may see custom slash commands described separately from Skills.
The current documentation says custom commands have been merged into the Skills model. A file such as
.claude/commands/deploy.md
and a Skill such as
.claude/skills/deploy/SKILL.md
both provide /deploy. Skills add capabilities such as supporting files, invocation controls, and automatic invocation. Existing command files continue to work.
So I would not spend too much time memorizing “slash command versus Skill” as if they are unrelated concepts.
For current Claude Code, the more useful mental model is:
A slash invocation is the user-facing way to run a reusable capability; Skills are the broader mechanism behind that capability.
The folder name also matters. Claude Code derives the command name from the Skill directory, so
.claude/skills/review/SKILL.md
gives you
/review
Now change the problem slightly.
Instead of asking Claude to run a review checklist, you want a dedicated security reviewer that investigates authentication, authorization, secrets, and sensitive-data handling. You want that work isolated from the main conversation because it may involve a lot of code and tool output.
That is where a subagent starts to make sense.
Claude Code describes subagents as specialized AI assistants with their own context window, system prompt, tool access, and permissions. They are particularly useful when a side task would otherwise flood the main conversation with search results, logs, or file contents.
The difference is easiest to see in the wording.
A Skill is
Run this procedure.
A subagent is
Act as this specialist and investigate this class of problem.
For example
Main Claude | +-- implementation | +-- testing | +-- security subagent | +-- auth +-- authorization +-- secrets +-- data exposure
The security subagent can work in its own context and return the findings to the main conversation. Anthropic also supports limiting which tools a subagent can use, which makes specialized workers useful for controlled workflows.
These mechanisms aren’t competing choices.
A review Skill could define the overall review procedure, while a specialized subagent performs one part of it.
For example
Claude Code supports running Skills in subagents and pre Skills into subagents, so the two mechanisms can be composed rather than treated as mutually exclusive.
That becomes useful when a workflow grows more complicated.
Plan Mode solves a different problem altogether.
Suppose you ask Claude:
Refactor our payment processing flow and replace the current transaction abstraction across the service.
That’s the kind of change where immediately editing files may be the wrong first move.
Plan Mode lets Claude inspect the repository, explore the relevant code, and produce a plan without modifying source files. You can then review that plan and move into an execution mode.
So I would separate the questions
CLAUDE.md
What should Claude generally know about this project?
**Skill / **/review
What reusable procedure do I want to invoke?
Subagent
What specialized worker should handle a particular class of task?
Plan Mode
Should Claude investigate and propose the approach before making changes?
Once you look at the problem this way, the features stop feeling like four competing ways to do the same thing.
Imagine a repository where CLAUDE.md has grown into this
Coding standards
API conventions
PR review checklist
Security checklist
Release procedure
Database migration procedure
Incident response procedure
Documentation process
Deployment process
There is nothing technically preventing this, but it is hard to reason about.
*Anthropic’s current guidance is actually quite direct on this point: keep *CLAUDE.md focused on facts and instructions Claude should have broadly, and move multi-step procedures or guidance relevant only to part of the codebase into Skills or path-scoped rules.
This is also a context-management issue.
A long review procedure doesn’t need to be sitting in the initial context when you’re debugging a single null-pointer exception. A Skill’s body loads when it is used, which is one reason Skills scale better for longer procedures.
For a typical repository, I’d start with something like
project/├── CLAUDE.md└── .claude/ ├── skills/ │ ├── review/ │ │ └── SKILL.md │ └── generate-tests/ │ └── SKILL.md └── agents/ └── security-reviewer.md
Then the responsibilities are obvious.
CLAUDE.md contains the project's standing conventions.
review contains the review procedure.
generate-tests contains a repeatable testing workflow.
security-reviewer represents a specialized worker.
And when a task is risky enough to warrant investigation before editing, I switch to Plan Mode.
It’s a small distinction, but it makes the whole setup easier to maintain.
The easiest way I know to remember all of this is
CLAUDE.md ↓"What should Claude generally know?"Skill / /review ↓"What reusable workflow should I run?"Subagent ↓"What specialized worker should handle this?"Plan Mode ↓"Should we understand the change before executing it?"
That is also why a code-review checklist is a good example.
If every review begins with the same eight instructions, don’t make developers paste them forever. Turn the procedure into a reusable Skill and invoke it as /review.
If the behavior should influence almost every development task, it probably belongs in CLAUDE.md.
If the work needs a specialized role, independent context, or restricted tools, a subagent may be the better fit.
And if the change is large enough that you don’t want Claude editing first and explaining later, use Plan Mode.
The goal isn’t to configure Claude Code as much as possible.
The goal is to give each instruction the right home.
Claude Code becomes more useful as a development tool when its instructions are organized with the same discipline we apply to software itself.
Not every rule belongs in CLAUDE.md. Not every repeated prompt needs a subagent. And not every complex change needs to start with execution.
Keep the things that define how the repository works in CLAUDE.md. Turn repeatable procedures into Skills that developers can call when they need them. Use subagents when a task deserves a specialized role and its own context. When the change is complex or the impact is difficult to predict, use Plan Mode before touching the code.
The real benefit is not having more Claude Code features. It is having a development workflow where each piece of guidance has a clear purpose and a clear place.
Good Claude Code configuration is less about adding instructions and more about knowing which instructions should not be there.
Claude Code Skills vs Slash Commands vs Subagents: Where Should Each One Live? was originally published in Towards AI on Medium, where people are continuing the conversation by highlighting and responding to this story.