Claude Code skills, explained: skills vs commands vs subagents
The short answer: A skill is a folder holding a SKILL.md file that Claude loads when it's relevant or when you type its name. Custom commands have been merged into skills; subagents are separate helpers with their own workspace.
Key points
- A skill loads its instructions only when it is used, so long reference material costs almost nothing until needed.
- Custom commands have been merged into skills; old files in .claude/commands/ still work.
- A subagent is a helper with its own context window: it does a job on the side and returns a summary.
- Work from the cheapest option: a line in CLAUDE.md, then a skill, then a subagent.
On this page
- What is a skill in Claude Code?
- Where do skills live?
- What does a skill look like?
- What happened to slash commands?
- What is a subagent?
- What is the difference between a skill and a subagent?
- And how is that different from CLAUDE.md?
- Which one should I make first?
- What makes a skill good?
- How do I know a skill loaded?
- A short checklist
What is a skill in Claude Code?
A skill is a folder with one file in it, SKILL.md, that teaches Claude how to do one kind of job. The file has a short header (a name and a description) and then instructions in plain language (Claude Code docs: skills).
You can use a skill two ways. You can type /skill-name yourself. Or you can leave it alone, and Claude loads the skill when your request matches its description.
The important part is that a skill’s body loads only when it is used. The docs say long reference material costs almost nothing until it is needed. That is the main difference from CLAUDE.md, which loads every time.
Where do skills live?
The docs list several places. The two you will use most:
.claude/skills/<skill-name>/SKILL.mdinside your project, for skills that belong to that project. Commit it and everyone on the project gets it.~/.claude/skills/<skill-name>/SKILL.mdin your home folder, for skills you want in every project.
Plugins can also bring skills, and organizations can roll them out to everyone. If two skills share a name, the docs say enterprise beats personal, and personal beats project.
What does a skill look like?
Here is the shape the docs show, shortened:
---
name: deploy
description: Deploy the application to production
disable-model-invocation: true
---
Deploy $ARGUMENTS to production:
1. Run the test suite
2. Build the application
3. Push to the deployment target
4. Verify the deployment succeeded
The description matters most. Claude uses it to decide when the skill applies, so write what the skill does and when to use it.
Tip
The disable-model-invocation: true line means only you can start it. That is a good idea for anything with side effects, like deploying.
The docs recommend keeping SKILL.md under 500 lines, with extra files such as scripts or reference notes beside it.
What happened to slash commands?
They became skills. The docs state that custom commands have been merged into skills. Your old files in .claude/commands/ still work, and Claude can start them on its own too. For new work the docs say to prefer skills, because a skill can carry extra files such as scripts.
Practically: if you typed /something before, you can still do that. A command file is now just a simpler skill.
What is a subagent?
A subagent is a helper that runs in its own context window with its own instructions and its own tool permissions. It does a job on the side and returns a summary, so the long search or test output stays out of your main conversation (Claude Code docs: subagents).
Claude Code has built-in ones. The docs name Explore (a fast, read-only agent for searching a project), Plan (a read-only research agent used in plan mode) and a general-purpose agent for multi-step work. You can add your own as a Markdown file in .claude/agents/, with a name and a description that tells Claude when to hand work over.
What is the difference between a skill and a subagent?
In one line: a skill is a set of instructions, and a subagent is a worker.
- A skill adds know-how to the conversation you are already having.
- A subagent does a task somewhere else and reports back.
- CLAUDE.mdLoads at the start of every session
- SkillLoads when relevant, or when you type /name
- SubagentWorks in its own context, sends back a summary
They can be combined, and the docs describe both directions. A skill can run in a subagent by setting context: fork, which makes it a task that runs in a separate helper. A subagent can also list skills in a skills field, which loads them as reference material.
Watch out
One warning from the docs: a skill that runs in a fork needs an explicit task. Guidelines alone produce nothing useful.
And how is that different from CLAUDE.md?
CLAUDE.md is always loaded. A skill is loaded on demand. That decides what goes where:
| CLAUDE.md | Skill | Subagent | |
|---|---|---|---|
| When it loads | Every session | When relevant or called | When Claude hands it a task |
| Best for | Short rules that always apply | A procedure you use sometimes | A job that would flood your conversation |
| Example | “Run npm test before you finish” |
“How we release the app” | “Search the whole project for every use of this function” |
The memory docs also say that CLAUDE.md is context, not enforced configuration. If something must be enforced, they point to hooks.
Which one should I make first?
Work from the cheapest option:
- Add a line to CLAUDE.md if it is a short rule that applies all the time.
- Write a skill when you catch yourself pasting the same long set of instructions again and again, such as how you release or how you review.
- Reach for a subagent when a job produces a lot of output you don’t need to read, or when you want a reviewer that has not seen your conversation.
Most people never need a custom subagent early on. The built-in ones are used automatically when they fit.
What makes a skill good?
- A clear description. It decides when Claude uses the skill. “Helps with deployment” is vague; “Deploy the app to production; use when asked to release” is better.
- One job. Two jobs make two skills.
- Steps that end in a check. End with something that passes or fails, so Claude can prove it did the work.
- Side effects off by default. Add
disable-model-invocation: trueto anything that publishes, deletes or sends.
How do I know a skill loaded?
Type / in Claude Code to see the commands and skills available to you. The docs note that skill content, once loaded, stays in the conversation for later turns. If a skill never seems to run on its own, the description is usually the problem: make it say plainly when the skill should be used.
A short checklist
- Always-on rules: CLAUDE.md.
- Sometimes-on procedures: a skill in
.claude/skills/. - Big side jobs: a subagent.
- Anything risky: set it so only you can start it.
- If you have old files in
.claude/commands/, they still work. New ones should be skills.
You do not need all of these on day one. Start with a short CLAUDE.md, add a skill the first time you repeat yourself, and let Claude use its built-in helpers.