Subagents Creator
Create Claude Code subagents - specialized AI assistants that run in isolated context windows.
What Subagents Provide
| Benefit |
Description |
| Context Isolation |
Each subagent has its own context, preventing main conversation pollution |
| Specialized Expertise |
Fine-tuned instructions for specific domains |
| Reusability |
Use across projects, share with team |
| Flexible Permissions |
Different tool access per subagent |
| Parallelization |
Multiple subagents can run concurrently |
Workflow
Step 1: Determine Subagent Requirements
Ask the user:
- What should this subagent do? (its specialty/purpose)
- What tools does it need? (see Available Tools below)
- When should it be triggered? (automatic vs explicit invocation)
Step 2: Determine Installation Scope
Ask where to install the subagent:
| Scope |
Path |
Use Case |
| Project |
.claude/agents/ |
Team-shared, committed to git |
| User global |
~/.claude/agents/ |
Personal agents for all projects |
| User profile |
~/.claude-<profile>/agents/ |
Profile-specific agents |
For user-level agents, ask which profile or if using default ~/.claude/.
Step 3: Create the Subagent
File Format
Create a Markdown file with YAML frontmatter:
---
name: agent-name
description: When this agent should be invoked. Use "proactively" to encourage automatic use.
tools: Read, Grep, Glob, Bash
model: sonnet
---
Your agent's system prompt goes here. Define its role, capabilities,
approach, and any specific instructions or constraints.
Configuration Fields
| Field |
Required |
Description |
name |
Yes |
Lowercase with hyphens (e.g., code-reviewer) |
description |
Yes |
When to invoke. Include "proactively" or "MUST BE USED" to encourage automatic delegation |
tools |
No |
Comma-separated list. Inherits all tools if omitted |
model |
No |
sonnet, opus, haiku, or inherit. Default: sonnet |
permissionMode |
No |
default, acceptEdits, bypassPermissions, plan |
skills |
No |
Comma-separated skill names to auto-load |
Step 4: Write Effective Prompts
Include in the system prompt:
- Role definition - Who the agent is
- Trigger behavior - What to do when invoked
- Process/checklist - Steps to follow
- Output format - How to present results
- Constraints - What NOT to do
See references/examples.md for complete working examples.
Available Tools
Read-Only:
Read - Read file contentsGlob - File pattern matchingGrep - Content search with regex
Execution:
Bash - Shell commandsEdit - Targeted file editsWrite - Create/overwrite files
Search:
WebFetch - Fetch URL contentWebSearch - Web searches
Other:
Skill - Execute skillsSlashCommand - Run slash commands
NOT Available: Task (prevents nested agent spawning)
Built-In Subagents
| Agent |
Model |
Tools |
Purpose |
| general-purpose |
Sonnet |
All |
Complex multi-step tasks |
| Plan |
Sonnet |
Read, Glob, Grep, Bash (read-only) |
Codebase research in plan mode |
| Explore |
Haiku |
Glob, Grep, Read, Bash (read-only) |
Fast codebase searching |
Invocation Methods
- Automatic - Claude delegates based on task matching
description
- Explicit - User mentions agent: "Use the code-reviewer agent..."
- CLI flag -
claude --agents '{...}' for session-only agents
Best Practices
- Focused purpose - Single clear responsibility per agent
- Detailed prompts - Include specific instructions, examples, constraints
- Minimal tools - Only grant necessary tools
- Action-oriented descriptions - Help Claude match tasks appropriately
- Version control - Commit project agents for team sharing
1---2name: subagents-creator3description: Guide for creating Claude Code subagents (custom agents) - specialized AI assistants with isolated context. Use when the user wants to create, add, or configure a subagent/custom agent for Claude Code.4---5
6# Subagents Creator
7
8Create Claude Code subagents - specialized AI assistants that run in isolated context windows.
9
10## What Subagents Provide
11
12| Benefit | Description |
13|---------|-------------|
14| Context Isolation | Each subagent has its own context, preventing main conversation pollution |
15| Specialized Expertise | Fine-tuned instructions for specific domains |
16| Reusability | Use across projects, share with team |
17| Flexible Permissions | Different tool access per subagent |
18| Parallelization | Multiple subagents can run concurrently |
19
20## Workflow
21
22### Step 1: Determine Subagent Requirements
23
24Ask the user:
251. **What should this subagent do?** (its specialty/purpose)
262. **What tools does it need?** (see Available Tools below)
273. **When should it be triggered?** (automatic vs explicit invocation)
28
29### Step 2: Determine Installation Scope
30
31Ask where to install the subagent:
32
33| Scope | Path | Use Case |
34|-------|------|----------|
35| Project | `.claude/agents/` | Team-shared, committed to git |
36| User global | `~/.claude/agents/` | Personal agents for all projects |
37| User profile | `~/.claude-<profile>/agents/` | Profile-specific agents |
38
39For user-level agents, ask which profile or if using default `~/.claude/`.
40
41### Step 3: Create the Subagent
42
43#### File Format
44
45Create a Markdown file with YAML frontmatter:
46
47```markdown
48---
49name: agent-name
50description: When this agent should be invoked. Use "proactively" to encourage automatic use.
51tools: Read, Grep, Glob, Bash
52model: sonnet
53---
54
55Your agent's system prompt goes here. Define its role, capabilities,
56approach, and any specific instructions or constraints.
57```
58
59#### Configuration Fields
60
61| Field | Required | Description |
62|-------|----------|-------------|
63| `name` | Yes | Lowercase with hyphens (e.g., `code-reviewer`) |
64| `description` | Yes | When to invoke. Include "proactively" or "MUST BE USED" to encourage automatic delegation |
65| `tools` | No | Comma-separated list. Inherits all tools if omitted |
66| `model` | No | `sonnet`, `opus`, `haiku`, or `inherit`. Default: `sonnet` |
67| `permissionMode` | No | `default`, `acceptEdits`, `bypassPermissions`, `plan` |
68| `skills` | No | Comma-separated skill names to auto-load |
69
70### Step 4: Write Effective Prompts
71
72Include in the system prompt:
731. **Role definition** - Who the agent is
742. **Trigger behavior** - What to do when invoked
753. **Process/checklist** - Steps to follow
764. **Output format** - How to present results
775. **Constraints** - What NOT to do
78
79See `references/examples.md` for complete working examples.
80
81## Available Tools
82
83**Read-Only:**
84- `Read` - Read file contents
85- `Glob` - File pattern matching
86- `Grep` - Content search with regex
87
88**Execution:**
89- `Bash` - Shell commands
90- `Edit` - Targeted file edits
91- `Write` - Create/overwrite files
92
93**Search:**
94- `WebFetch` - Fetch URL content
95- `WebSearch` - Web searches
96
97**Other:**
98- `Skill` - Execute skills
99- `SlashCommand` - Run slash commands
100
101**NOT Available:** `Task` (prevents nested agent spawning)
102
103## Built-In Subagents
104
105| Agent | Model | Tools | Purpose |
106|-------|-------|-------|---------|
107| general-purpose | Sonnet | All | Complex multi-step tasks |
108| Plan | Sonnet | Read, Glob, Grep, Bash (read-only) | Codebase research in plan mode |
109| Explore | Haiku | Glob, Grep, Read, Bash (read-only) | Fast codebase searching |
110
111## Invocation Methods
112
1131. **Automatic** - Claude delegates based on task matching `description`
1142. **Explicit** - User mentions agent: "Use the code-reviewer agent..."
1153. **CLI flag** - `claude --agents '{...}'` for session-only agents
116
117## Best Practices
118
1191. **Focused purpose** - Single clear responsibility per agent
1202. **Detailed prompts** - Include specific instructions, examples, constraints
1213. **Minimal tools** - Only grant necessary tools
1224. **Action-oriented descriptions** - Help Claude match tasks appropriately
1235. **Version control** - Commit project agents for team sharing
majiayu000