Slash Commands and Subagents in Claude Code: Building Reusable Workflows Beyond CLAUDE.md

You've got a CLAUDE.md file dialed in. Maybe you've wired up an MCP server or two so Claude Code can query your database or hit an internal API. And yet every session still starts the same way: you re-explain what you want, re-paste the same review checklist, re-describe the same multi-step process you ran yesterday. CLAUDE.md tells Claude Code who you are and how your repo is shaped. It doesn't tell Claude Code what to do, repeatedly, on demand, the same way every time.

That's the gap slash commands and subagents fill. Together they turn Claude Code from a smart chat window into something closer to an orchestration layer — a place where you define a task once and invoke it forever, and where a coordinating agent can delegate pieces of that task to specialized workers instead of doing everything itself in one long, tangled context window.

This piece is about that extensibility layer specifically: how to author custom slash commands, how to think about the orchestrator–subagent relationship, how to compose the two into a workflow you'd actually trust to run unattended-ish, and — just as important — when a "workflow" is overkill and a plain prompt would serve you better.

What CLAUDE.md and MCP Don't Do

Quick positioning, because this is where people get confused.

CLAUDE.md is context. It's the standing instructions and repo knowledge that Claude Code loads automatically — your conventions, your architecture notes, the "never touch this file" warnings. It's passive. It shapes how Claude Code behaves, but it doesn't give you a callable, parameterized action.

MCP servers are capability. They give Claude Code new tools — the ability to query Postgres, hit Cloudflare's API, read from Neon, whatever you've wired up. MCP expands what Claude Code can reach, not what Claude Code repeatedly does with what it can reach.

Neither one gives you a reusable, invokable procedure. If your review process is "check for N+1 queries, verify error handling matches our FastAPI exception pattern, confirm tests exist, flag anything touching auth," CLAUDE.md can describe that standard once as background knowledge, but you still have to ask for it explicitly, in your own words, in each session — and the phrasing drift between sessions means you get slightly different behavior each time. A slash command turns that description into a named, parameterized, versioned action: /review-pr 482. Same steps, every time, checked into git alongside the code it reviews.

That's the practical answer to "what does this add beyond CLAUDE.md and MCP": repeatability and composability. CLAUDE.md is memory. MCP is reach. Slash commands and subagents are procedure — the layer where a one-off prompt becomes a workflow engine.

Custom Slash Commands in Claude Code

A custom slash command is a prompt template stored as a file, invoked with a short trigger, that can accept arguments and be scoped to your whole team via the repo or just to you locally. Instead of typing a paragraph of instructions, you type /deploy-check staging and Claude Code expands that into the full instruction set, with staging substituted wherever you've referenced it.

Authoring one:

1. Name the action, not the topic. /fix-flaky-test is a better command name than /testing — it should read like a CLI subcommand.
2. Write the prompt as if delegating to a competent junior engineer who doesn't know your context yet. Spell out the steps, the acceptance criteria, and what "done" looks like. Vague commands produce vague runs.
3. Parameterize the parts that change. A PR number, a branch name, an environment, a file path. Everything else stays fixed in the template.
4. Decide the scope. Commands that make sense for anyone touching the repo belong checked into the project; commands that are personal habits (your own commit-message style, your own debugging ritual) belong in your local user-level config.
5. Keep it single-purpose. A command that tries to lint, test, deploy, and write release notes in one shot is a workflow pretending to be a command. Split it — and then, if the steps genuinely need to happen in sequence with different concerns at each stage, that's your cue to reach for subagents rather than one enormous prompt.

The habit worth building: any time you catch yourself typing a similar multi-paragraph instruction for the second time, stop and turn it into a command. The first time is a prompt. The second time is a pattern. The third time, without a command, is wasted effort.

This is also where a lot of the "power user" reputation around Claude Code actually lives — not in cleverer single prompts, but in a well-curated library of commands that encode how your team actually ships software. It's less flashy than watching an agent write code, but it's the difference between a tool you configure once and a tool you re-explain yourself to daily.

The Orchestrator–Subagent Model

Once you have more than a couple of steps that each require a different kind of attention, a single flat prompt starts to strain. This is the problem subagents solve.

Think of it as a small team, not a single brain. The orchestrator is the Claude Code session you're directly talking to — it holds the overall goal, decides what needs to happen, and delegates pieces of the work. A subagent is a separate, scoped agent invocation that gets a narrower task, its own context, and (this matters) doesn't pollute the orchestrator's context window with all its intermediate reasoning. It works the sub-task and reports back a result, not a transcript.

Why this matters practically:

• Context isolation. A code-review subagent doesn't need to know the deployment history from three tasks ago. Keeping it scoped means it reasons better and cheaper.
• Specialization. You can give a "test-writer" subagent a different persona and instruction set than a "security-reviewer" subagent, even though both are "Claude" under the hood. The prompt is the specialization.
• Composability. The orchestrator can call the same subagent from multiple different commands. A run-tests subagent might be invoked by /ship-feature, /hotfix, and /nightly-check alike.

A useful way to picture this multi-agent structure:

Role	Holds	Typical job	Reports
Orchestrator	Overall goal and running state	Decides what needs doing next, delegates, integrates results	Final summary to you
Subagent (e.g., planner)	A narrow task and just enough context to do it	Produces a plan, diff, test file, review	A discrete result back to orchestrator
Subagent (e.g., reviewer)	Its own scoped context	Checks output against a standard	Pass/fail plus notes

Multi-agent matters here for the same reason it matters in human teams: a single person trying to hold "design the API, write the code, write the tests, review the code, write the changelog" all in their head at once does a worse job of each than people who each hold one piece well. The orchestrator's job is coordination, not doing everything itself.

Defining a subagent in practice means writing a role description: what it's responsible for, what inputs it expects, what shape its output should take, and — critically — what it should not do (a test-writing subagent that starts refactoring your architecture has overstepped its brief). You then reference that subagent from within a command, so the command becomes the script and the subagents become the cast.

Plans First, Then Code

One pattern worth adopting deliberately: don't let the orchestrator jump straight to editing files. Structure the workflow so a planning phase produces a concrete, readable plan — which files change, what the approach is, what the risks are — before any coding subagent touches the repo.

This matters for two reasons. First, a plan is cheap to review and cheap to reject; a half-written implementation is not. Catching a wrong approach at the plan stage costs you thirty seconds of reading; catching it after the coding subagent has already touched six files costs you a revert and a re-run. Second, the plan becomes the shared contract between subagents — the coding subagent, the test-writing subagent, and the review subagent can all work against the same plan instead of each inferring intent independently and drifting apart.

A /ship-feature command built this way:

1. Orchestrator asks a planner subagent for an implementation plan → stops for your approval
2. On approval, dispatches a coding subagent against that plan
3. Dispatches a test-writer subagent and a docs-update subagent in parallel (neither depends on the other's output)
4. Runs a review subagent against the combined diff
5. Orchestrator summarizes and asks you to confirm before anything is committed

That parallel step matters for the same reason it matters in a real team: tasks that don't depend on each other's output shouldn't be forced into a queue. If writing tests and updating the changelog both only need the finished code diff, running them one after another wastes wall-clock time for no gain in quality.

Transparency and Traceability of Multi-Agent Runs

The obvious worry with any orchestrator-delegates-to-subagents setup is: how do you know what actually happened? If four agents each did something and you only see a final summary, you've traded a slow, legible process for a fast, opaque one — and opaque is a bad trade when the output is going into production code.

The practical mitigation is to design your commands so traceability is a first-class output, not an afterthought:

• Have the orchestrator report which subagent did what, not just a merged final answer. "Planner proposed X, coder implemented X with one deviation (Y), reviewer flagged Z" is far more auditable than "Done — added the feature."
• Keep plans and intermediate outputs visible artifacts — a plan subagent's output should be something you can read as a plan, not just internal reasoning you never see.
• Treat the final summary as a diff you review, not a decision you rubber-stamp. Multi-agent workflows are still generating code that goes into your repo; the review discipline you'd apply to a junior engineer's PR still applies here.

This is less about any specific tooling feature and more about a design discipline: build your commands so that every subagent hop leaves a trace you can follow after the fact, especially before you let a workflow run with less supervision.

When to Use a Workflow (and When Not To)

This is the judgment call that actually separates a productive power user from someone who's built an elaborate machine to answer questions a plain prompt would've handled fine.

Reach for a command-and-subagent workflow when:

• You do the same multi-step process more than twice — code review against a standard checklist, a release process, a recurring migration pattern.
• The task genuinely decomposes into independent concerns (write code / write tests / review / document) that benefit from separate context and separate framing.
• Some steps can run in parallel, and the wall-clock savings are worth the added coordination complexity.
• You want the process to be consistent across a team, not dependent on whoever happens to be prompting that day.
• The task is high-stakes enough that a plan-first checkpoint is worth the extra round trip.

Don't reach for it when:

• It's a one-off question or a single-file fix. A plain prompt is faster to write and faster to reason about than authoring a command you'll use once.
• The task doesn't actually decompose — if there's no meaningful separation of concerns, splitting it into subagents just adds coordination overhead and more places for context to get lost between hops.
• You need a fast, exploratory answer. Orchestration adds latency and layers of indirection; sometimes you just want Claude Code to look at a file and tell you what's wrong.
• You haven't yet done the task manually enough times to know what "correct" looks like. Automating a process you don't fully understand yourself just automates your uncertainty.

A decent rule of thumb: if you can't describe the workflow's steps and success criteria in a few clear sentences before you build it, you're not ready to encode it as a command — you're still figuring out the task, and that's better done as a plain conversation with Claude Code first.

Putting It Together

The mental model worth carrying away: CLAUDE.md is what Claude Code knows about your project. MCP is what Claude Code can reach outside itself. Slash commands are the reusable scripts that turn a description into an invokable action. Subagents are how you delegate pieces of a complex action to narrower, better-scoped workers instead of overloading one context window. And the discipline of plan-first, parallelize-where-independent, and keep-every-hop-traceable is what keeps that whole system trustworthy enough to actually rely on.

None of this replaces judgment about when to build a workflow versus when to just ask a direct question — if anything, the tooling makes that judgment more important, because it's now cheap enough to over-engineer a one-off task into a permanent fixture nobody remembers building. Start with the commands you've genuinely typed more than twice, give subagents narrow and honest job descriptions, and let the workflow earn its complexity one repeated task at a time.

FAQ

Do slash commands replace CLAUDE.md? No — they serve different jobs. CLAUDE.md is standing context loaded automatically; slash commands are explicit, parameterized actions you invoke on demand. Most solid setups use both together.

Can a subagent call another subagent? The pattern to design for is the orchestrator coordinating multiple subagents, each scoped to a distinct task, rather than building deep chains of subagents calling subagents — deep chains make traceability harder and are usually a sign the task needs to be broken into a clearer top-level plan instead.

How many subagents is too many for one workflow? There's no fixed number — the useful question is whether each subagent has a genuinely distinct concern and output. If two subagents' jobs overlap or one is just relaying the other's output unchanged, merge them.

Is a workflow always faster than a plain prompt? No. For one-off or exploratory tasks, a plain prompt is almost always faster, because you skip the design and review overhead of a multi-step command. Workflows pay off on repeated, decomposable, higher-stakes tasks.