Claude Code Skills vs Subagents: The Real Difference
You explain your project's conventions to Claude Code once, it does the task well, and then next session you're typing the same explanation again — use Prisma not raw SQL, colocate tests, don't invent a new folder for one component. That repetition is the actual cost of not having skills and subagents set up, and it compounds across every teammate doing the same re-explaining. A Claude Code skill is an instruction file that Claude loads automatically when its description matches what you're asking for, so the convention only has to be written once.
Skills and subagents get used interchangeably in conversation, but they are not the same mechanism, and picking the wrong one for the job is why some setups feel like they barely help. This article walks through what each one actually does, where slash commands fit between them, and how to tell during setup which one a given piece of knowledge belongs in.
What Is a Claude Code Skill?
A skill is a SKILL.md file with YAML frontmatter — a name and a description — plus instructions in the body. Claude Code scans that description against your current request and loads the matching skill's instructions into context before it responds, without you invoking anything by name.
That makes skills the right place for conventions Claude should follow inside your main conversation: how your team scaffolds a component, which ORM you use and how, what a commit message should look like. You write it once, and every future request that resembles the trigger phrasing gets the same treatment automatically.
What Is a Subagent, and How Is It Different From a Skill?
A subagent is a delegated role with its own system prompt and its own tool budget, separate from your main conversation. Claude hands a bounded job to it — review this diff, debug this failure, plan this refactor — and the subagent works in a fresh context before reporting a result back.
The isolation is the point. A code review subagent can read every changed file, run tests, and reason step by step without any of that scratch work eating into the context budget of the conversation you're actually having. Skills shape how Claude behaves; subagents give Claude somewhere separate to do a self-contained job.
How Do Skills, Subagents, and Slash Commands Compare?
Slash commands sit on top of both — they are short, typed entry points like /review or /plan that dispatch to the skill or subagent that actually does the work. The table below lines up how each one triggers and what it's built for.
| Asset | How it triggers | Best for |
|---|---|---|
| Skill | Automatic — description matches your prompt | Conventions used inside the main conversation |
| Subagent | Delegated — Claude hands off a bounded job | Isolated multi-step work: review, debug, test-writing |
| Slash command | Manual — you type the command | A short, memorable way to invoke a known skill or subagent |
A typical command set covers the workflows a team runs often enough to want a fixed name for: something like /plan to sequence a task, /review before a merge, /debug when a failure won't reproduce, /test to write coverage, /ship to walk through a release, plus narrower ones like /scaffold-component, /add-endpoint, /add-stripe-webhook, and /security-audit. Each is a thin wrapper — type the command, add your description, and Claude routes to the right skill or subagent instead of you having to remember which one applies.
How Do You Install a Skill in Claude Code?
Manual install takes four steps and works for a single skill or a whole folder of them.
- Create a skills/ folder inside your project's .claude/ directory, or the user-level equivalent to apply it across every project.
- Copy the skill's folder — its SKILL.md and any supporting files — into that directory unchanged.
- Restart Claude Code so it re-scans the available skills.
- Send a prompt that matches the skill's description and confirm it loads before you rely on it.
A pack shipped as a plugin, with a .claude-plugin/plugin.json manifest, installs faster: one command from inside the unpacked folder registers everything at the user level in one pass instead of copying folders individually. That's the difference between spending an afternoon wiring up sixty files by hand and running a single install step, then trimming or editing what you don't need.
Why Does a Skill Sometimes Fail to Trigger?
Skills match on the wording in their description field, not on keywords buried in the instructions, so a description that's too narrow misses requests a person would obviously recognize as the same task. If you ask for something and the skill you expected doesn't fire, the fix is almost always tightening that one sentence, not rewriting the skill itself.
Say a skill's description reads “scaffold a Next.js page component.” A request phrased as “add a new route for the settings screen” describes the same job in different words, and a narrow description misses it. Broadening the description to cover the phrasing your team actually uses, including the words a non-obvious teammate would reach for, closes that gap without touching the instructions underneath.
This is also why a skill you wrote for yourself six months ago quietly stops covering how you actually phrase requests today — the description drifts out of sync with your habits, and nobody notices until the skill goes silent. Revisiting descriptions periodically, the same way you'd revisit a README, keeps the automatic part of automatic actually true.
When Does Writing Your Own Stop Being Worth It?
Writing one skill for something unusual about your codebase takes twenty minutes and is worth doing yourself. Covering a full stack — web framework, API layer, database, testing, CI, deploy, security review — as separate SKILL.md files, plus a matching set of subagents and the slash commands that wire them together, is a different scale of work, and it's where a maintained pack starts to make sense instead of a weekend project.
The Claude Code Skills & Subagents Pack ships 34 skills across eight areas, 4 subagents (planner, reviewer, debugger, test-writer), and 23 slash commands wiring all of it together, installable as a plugin with one command or copied piece by piece into .claude/. If you're setting this up for a team that ships across more than one stack, starting from a working set and editing the descriptions that don't match your habits is faster than writing sixty files from a blank page.
Isn't It Cheaper to Just Build This Yourself?
For a single skill, yes — write it, done. The real cost is maintenance: when a stack you cover takes a major version bump, every SKILL.md that assumed the old conventions needs a pass, and that upkeep is easy to defer indefinitely on a self-maintained set until Claude starts producing outdated code again. If your stack coverage is narrow, building your own is the right call. If it spans several frameworks and you'd rather not own the update cycle, a maintained pack — reissued when a covered stack changes — trades a fixed cost now for skipping that ongoing upkeep.
The same idea applies if your team runs Cursor instead of or alongside Claude Code: Cursor uses its own rule files rather than SKILL.md, but the Cursor Rules Mega-Pack covers the equivalent ground with 1,700+ rule entries across 20 stacks in both the legacy .cursorrules and modern .cursor/rules/*.mdc formats.
Where Do You Start?
Pick one repeated instruction you've retyped into Claude Code more than twice and turn it into a SKILL.md this week — that's the fastest way to feel the difference before deciding whether to build out the rest by hand or start from a maintained set. Browse the full BuyCoded catalog to see every skills, rules, and prompt pack available and compare what's already built against what you'd be writing from scratch.
Frequently asked questions
What is the main difference between a Claude Code skill and a subagent?
A skill is a SKILL.md instruction file that Claude Code loads into the current conversation automatically when its frontmatter description matches your request, shaping how Claude does one kind of task. A subagent is a separate delegated role with its own system prompt and tool budget that runs a bounded job, such as a review or a debug pass, and reports back without cluttering your main context.
Do subagents replace the need for skills?
No. They solve different problems and most real setups use both. Skills carry the conventions Claude should follow while working in your main conversation — naming, stack idioms, project structure. Subagents handle jobs that benefit from a clean, isolated context, like a security audit or a test-writing pass, where you want a verdict back rather than a running commentary.
Where do I put a SKILL.md file so Claude Code picks it up?
Project-level skills go in a skills/ folder inside your project's .claude/ directory; user-level skills go in the equivalent folder under your home directory's Claude Code config so they apply across every project. Either way the file needs YAML frontmatter with a name and a description, since that description is what Claude matches against your prompt.
Can slash commands work without any skills or subagents installed?
A slash command still runs as plain instructions if it does not reference a skill or subagent, but most useful ones are thin wrappers that dispatch to one. The command gives you a short, memorable entry point; the skill or subagent underneath does the actual work, so removing that target usually turns the command into an empty shortcut.
Why does a Claude Code skill sometimes not trigger when I expect it to?
Skills load by matching your prompt's wording against the description field in the skill's frontmatter, not by keyword, so a vague or narrow description misses requests a human would recognize as the same task. Rewriting the description to cover the phrasing you actually type is usually the fix, not rewriting the skill's instructions.
Is it worth writing your own skills instead of buying a pack?
For one or two skills tied to something unusual about your codebase, writing your own is fast and worth it. For broad stack coverage — web framework, database, testing, deploy, security — writing and maintaining dozens of SKILL.md files by hand is a real ongoing cost, which is why many teams start from a maintained pack and edit from there instead of starting blank.