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:
markdown
--- 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 contents - •
Glob- File pattern matching - •
Grep- Content search with regex
Execution:
- •
Bash- Shell commands - •
Edit- Targeted file edits - •
Write- Create/overwrite files
Search:
- •
WebFetch- Fetch URL content - •
WebSearch- Web searches
Other:
- •
Skill- Execute skills - •
SlashCommand- 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