Skills vs Agents vs Commands

Claude Code really has two extension mechanisms, and they get conflated constantly because all three patterns are Markdown-based with YAML frontmatter (a skill is a folder whose SKILL.md carries the frontmatter, and can bundle supporting scripts and templates alongside it). But they answer three different questions. A subagent answers "who should Claude hand this off to?" A skill answers "what does Claude need to know to do this well?" A skill invoked as a slash command answers "what do I want to type to kick this off?" Pick the wrong one and you end up fighting the tool — a skill that never loads, an agent that never gets delegated to, a command nobody remembers exists.

This guide draws the lines clearly, gives you a decision table, and walks through real "I want to..." cases so you reach for the right one on the first try.

Two mechanisms, three invocation patterns

Everything lives under .claude/ (project-local) or ~/.claude/ (personal, follows you everywhere). There are two real mechanisms — subagents and skills — and the third "slash command" pattern is just a skill you trigger by name.

.claude/
├── agents/                  # subagents — isolated delegates Claude calls on its own
│   └── code-reviewer.md
├── skills/                  # skills — auto-loaded knowledge OR user-invoked /commands
│   ├── changelog/SKILL.md   # auto-loads when relevant
│   └── ship/SKILL.md        # disable-model-invocation: true → only fires on /ship
└── commands/                # legacy slash commands — still work, but skills are canonical
    └── ship.md

The crucial difference is who pulls the trigger and where the work runs.

• A subagent is a delegate. Claude decides, mid-task, that a chunk of work belongs to a specialist and hands it off. The subagent runs in its own context window with its own toolset and returns a summary. You don't invoke it directly; Claude routes to it based on its description.
• A skill is reusable expertise. It sits dormant until Claude notices the current task matches it, then loads its instructions into the main context to inform how Claude does the work. It's knowledge-on-demand, not a separate worker.
• A skill invoked as a slash command is that same mechanism, flipped to manual. Typing /ship expands a skill into the conversation as if you'd pasted it. It runs in your main context. The only difference from an auto-loaded skill is disable-model-invocation: true, which stops Claude from firing it on its own — so the trigger is always you.

The decision table

Read the table top to bottom on a single axis at a time. The invocation column is the fastest filter: if you want to be the one to press the button, it's a command. The context column is the next: only subagents get isolation, which is what makes them the right tool when a task would otherwise flood your main window with noise.

When to reach for a subagent

Choose a subagent when the work is a self-contained job with a noisy middle and a clean summary — and you want Claude to decide when to run it.

The isolated context window is the whole point. A subagent that runs the test suite can churn through hundreds of lines of failing output, then hand back just "three tests fail, all from the same null-check in parseDate()." Your main thread never sees the logs. That's also why subagents are right for parallel fan-out: Claude can dispatch several at once without their transcripts colliding.

---
name: test-runner
description: Runs the test suite and summarizes failures with root causes. Use after code changes or when a test is reported failing.
model: sonnet
tools: Read, Grep, Glob, Bash
---
 
You run the project's tests, read failing output, and report each
failure as: file, failing assertion, and most likely cause.
Do not fix code unless explicitly asked.

The description is the routing signal — it's how Claude decides to delegate, so write it in terms of when to use this agent with concrete triggers. Scope tools to the minimum the job needs; a read-only reviewer physically cannot edit your code.

When to reach for a skill

Choose a skill when there's a repeatable procedure or body of knowledge that should shape how Claude works, but only when the task actually calls for it.

The defining trait is on-demand loading. A skill's instructions don't sit in your context burning tokens every session — Claude pulls them in only when the current task matches the skill's description. That makes skills the right home for "the way we do X here" recipes: generating a release changelog, scaffolding a component to house conventions, following a specific data-migration playbook.

---
name: changelog
description: Generate a release changelog from merged PRs since the last tag, grouped by type, following our house format.
allowed-tools: Bash, Read
---
 
When asked to write a changelog:
1. Find the last release tag with `git describe --tags --abbrev=0`.
2. List merged PRs since that tag.
3. Group entries under Added / Changed / Fixed and link each PR.

A skill differs from a subagent in two ways that decide between them: it runs in your main context (no isolation — Claude uses the loaded steps directly), and it's knowledge, not a worker. If you don't need a separate context window and you're really just teaching Claude a procedure, it's a skill.

A skill can opt into isolation with context: fork in its frontmatter, which executes it in a forked subagent — useful when a skill's work would otherwise flood your main thread. That blurs the line a little, but the default and common case is main-context execution; reach for a full subagent when isolation is the point, not an afterthought.

When to reach for a slash command

Choose this pattern — a skill you only ever trigger by name — when you want to be the one who pulls the trigger, and it's a prompt you'd otherwise retype.

There's no autonomy and no isolation here — it's a saved prompt that happens to live in a skill. Typing /ship drops the skill's contents into the conversation. That's exactly what you want for deliberate, you-initiated workflows: the multi-step sequence you run before every PR, the scaffolding prompt you fire at the start of a feature, the review checklist you want on demand rather than whenever Claude guesses you want it. The one frontmatter flag that makes it user-only is disable-model-invocation: true.

---
description: Open a PR — summarize the diff, draft a title and body, push and create it.
argument-hint: [base-branch]
allowed-tools: Bash, Read
disable-model-invocation: true
---
 
1. Run `git diff $0...HEAD` and summarize the changes.
2. Draft a PR title (imperative) and a body with a Summary and Test plan.
3. Push the branch and open the PR with `gh pr create`.

Skills accept arguments ($0 for the first argument, $1 for the second, or $ARGUMENTS for all arguments as a single string) and an argument-hint, which makes them feel like CLI subcommands for your repo. Note the substitution is 0-indexed: $0 is the first argument, so a single-argument argument-hint: [base-branch] lands in $0, not $1. The decision between a user-triggered command and an auto-loaded skill comes down to invocation: if you want to type the name yourself, set disable-model-invocation: true; if you want Claude to reach for it automatically when the task fits, leave it off.

Worked examples: "I want to..."

"I want Claude to review every diff for bugs before I merge — without me asking each time." That's a subagent. The work is a self-contained job, it benefits from isolation (the review reasoning stays out of your main thread), and you want Claude to delegate to it automatically when a diff appears. Give it a sharp description with trigger examples and a read-only toolset.

"I want changelogs to always follow our exact house format, whenever one gets written." That's a skill. It's a reusable procedure that should shape how Claude works when the task comes up — no separate context needed, and you don't want to type a command every time. Claude loads it on demand whenever a changelog is in play.

"I want to type one thing before every PR that summarizes the diff, drafts the description, and opens the PR." That's a slash command — i.e. a skill with disable-model-invocation: true. You are the trigger, it runs in your main context, and it's a fixed prompt you fire repeatedly. /create-pr [base] and you're done.

Putting it together

Map the request to the question it answers. Who pulls the trigger — you (command) or Claude (agent/skill)? Does it need its own context window — yes (agent) or no (skill/command)? Is it knowledge that shapes the work, or a worker that goes off and does the work — skill or agent?

The three compose well. A slash command can lay out a sequence that delegates a noisy step to a subagent and leans on a skill for house conventions along the way. Start with the one that fixes your most repeated friction — usually a slash command for a workflow you retype, or a subagent for a task that keeps drowning your context — then layer the others as your setup matures.