Agent Creator
Create subagents as Markdown files with YAML frontmatter. Store in:
~/.claude/agents/- User-level (all projects).claude/agents/- Project-level (current project only)
Subagent File Structure
---
name: agent-name
description: When Claude should delegate to this agent
tools: Read, Grep, Glob
model: sonnet
---
System prompt instructions for the agent go here.
The agent receives only this prompt, not the full Claude Code system prompt.Required Fields
| Field | Description |
|---|---|
name | Unique identifier (lowercase, hyphens only) |
description | When to delegate - Claude uses this to decide. Include "use proactively" for automatic delegation |
Optional Fields
| Field | Default | Description |
|---|---|---|
tools | All | Comma-separated tool names. See configuration.md for full list |
disallowedTools | None | Tools to deny from inherited set |
model | sonnet | sonnet, opus, haiku, or inherit |
permissionMode | default | default, acceptEdits, dontAsk, bypassPermissions, plan |
skills | None | Skills to load into agent context at startup |
hooks | None | Lifecycle hooks (PreToolUse, PostToolUse, Stop) |
For detailed options and all available tools, see references/configuration.md.
System Prompt Guidelines
- Be specific about what the agent should do when invoked
- Include a clear workflow (numbered steps)
- Define output format expectations
- Keep focused on one domain/task
Examples
Read-Only Reviewer
---
name: code-reviewer
description: Reviews code for quality and security. Use proactively after code changes.
tools: Read, Grep, Glob, Bash
model: inherit
---
Review code and provide actionable feedback.
When invoked:
1. Run git diff to see recent changes
2. Focus on modified files
3. Check for: clarity, duplication, error handling, security, tests
Format feedback by priority:
- Critical (must fix)
- Warnings (should fix)
- Suggestions (consider)Read-Write Fixer
---
name: debugger
description: Debug and fix errors, test failures, unexpected behavior. Use proactively for issues.
tools: Read, Edit, Bash, Grep, Glob
---
Debug issues with systematic root cause analysis.
When invoked:
1. Capture error message and stack trace
2. Identify reproduction steps
3. Isolate failure location
4. Implement minimal fix
5. Verify solution
Provide: root cause, evidence, code fix, prevention.Hook-Validated Agent
---
name: db-reader
description: Execute read-only database queries for analysis and reports.
tools: Bash
hooks:
PreToolUse:
- matcher: "Bash"
hooks:
- type: command
command: "./scripts/validate-readonly.sh"
---
Execute SELECT queries only. Explain that write access is unavailable if requested.Best Practices
- Focus agents narrowly - One agent per domain/task
- Write clear descriptions - Claude uses these for delegation decisions
- Limit tools appropriately - Grant only what's needed
- Use hooks for validation - When you need finer control than tool restrictions
- Test with real tasks - Verify the agent behaves as expected