Author(s): Sudha Subramaniam

Originally published on Towards AI.

Claude Code Skills vs Slash Commands vs Subagents: Where Should Each One Live?

A practical way to organize Claude Code instructions, reusable workflows, and specialized agents without turning CLAUDE.md into a dumping ground

The problem isn’t knowing what Claude Code can do. It’s knowing where to put the behavior.

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.

CLAUDE.md: things Claude should generally know

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.

A review checklist has a different shape

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.

One terminology detail is worth knowing

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

When a subagent makes more sense

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.

Skills and subagents can work together

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 preloading 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 isn’t another place to store instructions

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.

The mistake is usually overloading one mechanism

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.

How I would structure a real project

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 mental model worth remembering

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.

Final Thought

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.

Join thousands of data leaders on the AI newsletter. Join over 80,000 subscribers and keep up to date with the latest developments in AI. From research to projects and ideas. If you are building an AI startup, an AI-related product, or a service, we invite you to consider becoming a sponsor.

Published via Towards AI