Claude Code Subagents: The System Prompts Behind a Good Specialist

What a Claude Code Subagent Is

A Claude Code subagent is a scoped helper the main agent delegates to. Each subagent gets its own system prompt, its own tool access, and its own context window. The orchestrator hands off a task, the subagent does the focused work in isolation, and only its result returns, which keeps the main thread from drowning in detail.

Most material on Claude Code subagents explains the file. The official sub-agents docs cover the YAML reference. Builder.io's subagents post walks creating and debugging them. The Shipyard quickstart is a solid intro. All three teach the mechanics: where the file lives, what fields it takes, how to invoke it.

What none of them ship is the part that decides whether the subagent is any good: the system prompt body. A specialist is only as sharp as its role, its tool scope, and its output contract. The YAML is the envelope. The prompt is the letter.

Why the YAML Isn't the Hard Part

Configuring a subagent file takes a minute. You name it, pick a model, list its tools, and write a description. Then you run it and discover the reviewer subagent rewrote three files because nothing told it to stay read-only, or it returned a wall of prose the orchestrator can't parse back into action.

The failure is never in the YAML. It's in a system prompt that didn't define the lane. A subagent without a tight role acts like a generalist with a fancy filename. A subagent without a tool scope reaches for whatever's available. A subagent without an output contract returns something the orchestrator has to re-parse, which defeats the point of delegating.

Three things make a subagent a specialist instead of a renamed default. Get those three into the system prompt and the YAML almost doesn't matter.

What Belongs in a Subagent System Prompt

• The role, narrow. One job, stated in two lines. "You audit diffs for security defects" beats a paragraph of persona. A subagent that does one thing well is worth more than one that does five things adequately.
• The tool scope, explicit. Name the tools it uses and, when it matters, the tools it must not. A reviewer reads and searches. It doesn't write or run shell.
• The output contract, locked. The exact shape the subagent returns to the orchestrator, so the result is machine-parseable, not an essay.
• The escalation rule. When the subagent should stop and hand back instead of guessing. "If the diff touches auth, flag it and return rather than approving."
• The refusal boundary. What the subagent declines. A test-writer doesn't also refactor the code under test.

That list is the difference between delegation that helps and delegation that creates cleanup work.

A Subagent System Prompt You Can Adapt

Here's the body for a read-only reviewer subagent. The YAML around it just points to this.

Role: You review code diffs for defects. You do not fix them.

Tool scope: read and search only. You never write files or run shell.

Task: Review the diff in {{diff}} for logic errors, missing error
handling, and security issues. Ignore style.

Output contract — return exactly this and nothing else:
- A markdown table: Severity | File:line | Issue | Suggested fix
- Blockers first. If none: "No blockers found."

Escalation: if the diff changes auth or payment code, mark every
finding as a blocker and add a one-line note: "Sensitive surface."

The tool-scope line does real work. Stating "read and search only, never write" inside the system prompt is a prompt-layer boundary that complements the YAML's tool list. Belt and suspenders, and on a subagent that runs unattended, you want both.

There's a second payoff that's easy to miss: context hygiene. Because a subagent runs in its own window, the orchestrator never sees the diff, the file contents, or the model's intermediate reasoning. It sees the contracted table and nothing else. That isolation is the real reason to delegate. A reviewer that reasons over 4,000 lines of diff would flood the main context if it ran inline. Pushed into a subagent, those 4,000 lines stay walled off, and the orchestrator gets back a clean ten-row table. The output contract isn't just about format. It's the membrane that keeps the subagent's mess out of the main thread.

How Models Honor a Subagent Contract

The role-scope-contract structure works across models, with differences worth knowing if you reuse the same body outside Claude Code.

The portable rule: state the tool scope and the refusal boundary as hard sentences, not soft suggestions, and put the output contract at the end. A subagent body written that way drops into any orchestrator without a rewrite.

Variables You'll Set

Getting Started

1. Write down the one job each subagent should own. One sentence each.
2. For each, state the tool scope: what it uses, what it must never touch.
3. Write the output contract as a fixed shape the orchestrator can parse.
4. Add an escalation rule and a refusal boundary.
5. Drop the body into the subagent's system prompt; the YAML just points to it.
6. Run it on a real task and tighten the scope where it overreaches.
7. For a ready-made policy body, start with the Coding Agent Guardrails System Prompt.

A subagent's tool scope is really a guardrail, and guardrails deserve their own treatment. The Coding Agent Guardrails System Prompt encodes the Always / Ask-first / Never tiers as a pasteable ## Boundaries block, which is exactly the safety layer a write-capable subagent needs.

A subagent earns its keep when it does one job, stays in scope, and returns something the orchestrator can act on. Write the body with that in mind and the YAML is an afterthought. For the file that configures the orchestrator itself, see how to write an AGENTS.md file with AI. And to turn a subagent into a one-keystroke command, Claude Code slash commands that stick covers the saved-body pattern.