Claude Code Agents vs Commands
A subagent (.claude/agents/*.md) is a role: a name, a tool grant, and a system prompt that runs in its own isolated context window when the main session or you delegate to it. A slash command (.claude/commands/*.md) is a prompt you trigger by typing /name, read by whichever session is already running. An agent is who does the work; a command is the order you ask for it in. Last updated 2026-10-30 by Rakshit Yadav.
Subagent: a role with its own context window
A Claude Code subagent is a markdown file under .claude/agents/<name>.md with frontmatter for name, description, which tools it's allowed to call, and optionally which model runs it. When the main session delegates to it — because you named it or because the main agent's own judgment matched the task to its description — that subagent runs in a clean, separate context window with no access to the parent conversation's history beyond what it was handed. It reports back a result; its working context then disappears. That isolation is the entire point: a long code review or a wide research pass can burn thousands of tokens of scratch work without any of it polluting the main thread.
Command: a prompt you trigger with /
A slash command is a markdown file under .claude/commands/<name>.md. Type /ship and the current session reads that file as a prompt — there is no separate context window, no isolation, just instructions injected into the conversation you're already having. A command never runs on its own; the model doesn't decide to invoke one the way it can choose to delegate to a subagent that matches a task description. You are always the trigger.
When to reach for a slash command
Reach for a command when you do the same multi-step job often enough that typing it out each time is wasted effort, and when you want to be the one deciding the moment it runs: a release checklist, a full SEO audit, a scaffold for a new API route. The command's body can itself instruct the session to delegate pieces of the job to subagents — that's the normal pattern, not an exception.
When to reach for a subagent
Reach for a subagent when a single job benefits from a clean context window separate from the main thread: a code review that needs to read a dozen files it will never mention again, a research pass that would otherwise flood the conversation with search results, or a role you want to invoke by name from several different commands without copy-pasting its instructions each time. If the job is small enough that burning a fresh context window is overkill, it doesn't need to be a subagent — it can just be the next line of the current conversation.
Combining both: a command that invokes an agent
/ship is the clearest example. Typing /ship doesn't spawn 34 separate processes — it tells the current session to read the command file, which instructs it to delegate in sequence: hand the spec to tech-lead, then the schema to a database subagent, then the endpoint to a backend subagent, each running in its own context window and reporting back before the next one starts. The command supplies the order and the gates between steps; each subagent supplies the isolated workspace and the role-specific system prompt for its piece. Neither replaces the other — a command with no subagents to delegate to is just a long prompt, and a subagent nobody ever invokes is a file that does nothing.
Decision table
| Subagent | Command | |
|---|---|---|
| File | .claude/agents/<name>.md | .claude/commands/<name>.md |
| Triggered by | Name, or the main agent's own judgment matching its description | You, typing /name |
| Context | Its own isolated window | The session you're already in — no isolation |
| Tool access | Scoped per-agent via frontmatter | Whatever the current session already has |
| Best for | A role or job that needs a clean, separate workspace | A repeatable sequence you want to trigger on purpose |
| Can it call the other? | No — an agent can't type a slash command | Yes — a command's instructions can tell the session to delegate to one or more subagents |
This is the same split as the Cursor-side question, just with real context isolation on the agent side instead of a shared single session — see Cursor Agents vs Commands for how that version plays out.
Related pages
Frequently asked questions
Can a Claude Code subagent run on its own, without a command?
Yes. The main session can delegate to a subagent directly, based on your explicit mention of its name or because the task matches its description, with no command file involved at all.Does /ship spawn 34 separate Claude Code sessions?
No. It runs in the current session, which then delegates specific steps to individual subagents one at a time, each getting its own context window for that step before control returns to the command's sequence.Should my checklist be a command or a subagent?
If you want to trigger it yourself and it's mostly a sequence of steps, make it a command. If a step in that sequence needs a large, separate context window — reading many files, running a long review — delegate that step to a subagent from inside the command.Can a subagent have a smaller tool grant than the main session?
Yes, and that's a common reason to use one. A subagent's frontmatter can restrict it to read-only tools, for example, so a review role can't accidentally edit files even if the main session has write access.
Get 34 roles and the slashes that route them
AgenticKit ships 34 subagents plus the commands that chain them in the right order, pre-wired for Claude Code.