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
markdown
--- 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
markdown
--- 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
markdown
--- 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
markdown
---
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