What is a Claude Code subagent?

A subagent is a specialized assistant Claude Code can delegate tasks to. Each one is a markdown file in .claude/agents/ with YAML frontmatter (name, description, optional tools and model) and a system prompt. Subagents run in their own context window, keeping the main conversation clean.

Where do I save the generated file?

Project subagents go in .claude/agents/ inside your repo (shared with your team, highest priority). Personal subagents go in ~/.claude/agents/ and work across all your projects.

Which tools should I give a subagent?

As few as it needs. A code reviewer needs Read, Grep, and Glob but not Write or Bash; giving fewer tools makes the agent safer and its behavior more predictable. Omit the tools field entirely to inherit all tools including MCP tools.

How does Claude decide when to use my subagent?

It reads the description field. Make it action-oriented and trigger-focused ('Use PROACTIVELY after any code change…') — vague descriptions mean the subagent never fires.

Is anything I type uploaded?

No — the generator is pure client-side JavaScript. Nothing leaves your browser.

Claude Code Subagent Generator — Free .claude/agents Builder

Anatomy

What makes a valid subagent file

A subagent is one markdown file: YAML frontmatter that controls routing and permissions, then the system prompt the subagent runs with.

🔑

name

Unique kebab-case identifier — it becomes how you invoke it (use the code-reviewer subagent) and the filename.

🎯

description

How Claude decides to delegate. Lead with the role, then the trigger: phrases like Use PROACTIVELY after code changes measurably increase automatic invocation.

🧰

tools

Optional allowlist. Omit to inherit everything (including MCP tools); list the minimum set for safety and predictability.

🧠

model + prompt

Optional model (sonnet/opus/haiku/inherit) plus the body — the subagent's entire system prompt. It starts with zero context from your conversation, so the prompt must stand alone.

Design tips

Subagents that actually get used

▹

One job per agent

A 'code-reviewer' outperforms a 'code-helper'. Narrow scope means a sharper prompt, fewer tools, and more reliable automatic delegation.

▹

Write the trigger into the description

Claude matches tasks against descriptions. 'Use PROACTIVELY when tests fail' fires; 'helps with testing' doesn't.

▹

Assume zero context

Subagents don't see your conversation. The prompt must say how to gather context itself — which files to read, which commands to run first.

▹

Version them with the repo

Keep project subagents in .claude/agents/ and commit them. Your whole team gets the same specialists, and improvements ship like code.

FAQ

Subagent questions

How do I use a subagent once it's saved?+

Claude Code delegates automatically when a task matches the description, or you can invoke it explicitly: 'use the code-reviewer subagent to check my changes'. Run /agents to see everything loaded.

Project vs personal subagents?+

Project subagents (.claude/agents/ in the repo) are shared with your team and win on name conflicts. Personal ones (~/.claude/agents/) follow you across projects.

Why does my subagent never trigger automatically?+

Almost always the description: it describes what the agent is instead of when to use it. Rewrite it trigger-first ('Use PROACTIVELY after…', 'MUST BE USED when…') and it starts firing.

Do subagents share my conversation context?+

No — each invocation starts with a clean context window containing only the subagent's system prompt and the task Claude hands it. That isolation is the point: research and noisy tool output stay out of your main thread.

Can a subagent use MCP tools?+

Yes. If you omit the tools field it inherits all tools including MCP servers'. To scope it, list the specific MCP tool names alongside built-ins.

Go further

Want 89 subagents already engineered?

This generator gives you a great starting file. The ClaudeThings kits give you the full bench — 89 production-grade agents plus the skills and commands they pair with.

🛠️

Engineering Kit

Battle-tested Claude skills & workflows for builders.

✓ 58 agents · 61 skills · 159 commands
✓ Security, testing & code-review skills
✓ Every skill formatted to spec
✓ Lifetime updates

Get the Engineering Kit

📣

For founders

Marketing Kit

Turn Claude into your growth team.

✓ 31 agents · 42 skills · 32 commands
✓ Content, SEO & email-sequence skills
✓ Landing-page & funnel templates
✓ Lifetime updates

Get the Marketing Kit

Or grab all 89 agents, 103 skills & 181 commands in the Complete Bundle →