Sub-agent Creator

Create specialized AI sub-agents for Claude Code that handle specific tasks with customized prompts and tool access.

Sub-agent File Format

Sub-agents are Markdown files with YAML frontmatter stored in:

• Project: .claude/agents/ (higher priority)

• User: ~/.claude/agents/ (lower priority)

Structure

name: subagent-name description: When to use this subagent (include "use proactively" for auto-delegation) tools: Tool1, Tool2, Tool3 # Optional - inherits all if omitted model: sonnet # Optional - sonnet/opus/haiku/inherit permissionMode: default # Optional - default/acceptEdits/bypassPermissions/plan skills: skill1, skill2 # Optional - auto-load skills

System prompt goes here. Define role, responsibilities, and behavior.

Configuration Fields

Field Required Description

name

Yes Lowercase with hyphens

description

Yes Purpose and when to use (key for auto-delegation)

tools

No Comma-separated tool list (omit to inherit all)

model

No sonnet , opus , haiku , or inherit

permissionMode

No default , acceptEdits , bypassPermissions , plan

skills

No Skills to auto-load

Creation Workflow

• Gather requirements: Ask about the sub-agent's purpose, when to use it, and required capabilities

• Choose scope: Project (.claude/agents/ ) or user (~/.claude/agents/ )

• Define configuration: Name, description, tools, model

• Write system prompt: Clear role, responsibilities, and output format

• Create file: Write the .md file to the appropriate location

Writing Effective Sub-agents

Description Best Practices

The description field is critical for automatic delegation:

Good - specific triggers

description: Expert code reviewer. Use PROACTIVELY after writing or modifying code.

Good - clear use cases

description: Debugging specialist for errors, test failures, and unexpected behavior.

Bad - too vague

description: Helps with code

System Prompt Guidelines

• Define role clearly: "You are a [specific expert role]"

• List actions on invocation: What to do first

• Specify responsibilities: What the sub-agent handles

• Include guidelines: Constraints and best practices

• Define output format: How to structure responses

Tool Selection

• Read-only tasks: Read, Grep, Glob, Bash

• Code modification: Read, Write, Edit, Grep, Glob, Bash

• Full access: Omit tools field

See references/available-tools.md for complete tool list.

Example Sub-agents

See references/examples.md for complete examples:

• Code Reviewer

• Debugger

• Data Scientist

• Test Runner

• Documentation Writer

• Security Auditor

Template

Copy from assets/subagent-template.md to start a new sub-agent.

Quick Start Example

Create a code reviewer sub-agent:

mkdir -p .claude/agents

Write to .claude/agents/code-reviewer.md :

name: code-reviewer description: Reviews code for quality and security. Use proactively after code changes. tools: Read, Grep, Glob, Bash model: inherit

You are a senior code reviewer.

When invoked:

1. Run git diff to see changes
2. Review modified files
3. Report issues by priority

Focus on:

• Code readability
• Security vulnerabilities
• Error handling
• Best practices