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 (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/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 trigger)
tools	No	Comma-separated tool list
model	No	sonnet, opus, haiku, or inherit
permissionMode	No	default, acceptEdits, plan, etc.
skills	No	Skills to auto-load
hooks	No	Hooks for lifecycle (PreToolUse, etc.)

Creation Workflow

1. Gather requirements: Ask about purpose, when to use, and capabilities
2. Choose scope: Project (.claude/agents/) or user (~/.claude/agents/)
3. Define configuration: Name, description, tools, model
4. Write system prompt: Clear role, responsibilities, and output format
5. 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 code.

# Good - clear use cases
description: Debugging specialist for errors, test failures, unexpected behavior.

# Bad - too vague
description: Helps with code

System Prompt Guidelines

1. Define role clearly: "You are a [specific expert role]"
2. List actions on invocation: What to do first
3. Specify responsibilities: What the sub-agent handles
4. Include guidelines: Constraints and best practices
5. 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 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 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 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

Hooks in Subagents

Define hooks that run during subagent execution:

---
name: code-reviewer
description: Review code with auto-linting
hooks:
  PostToolUse:
    - matcher: "Edit|Write"
      hooks:
        - type: command
          command: "./scripts/run-linter.sh"
---

Hooks are scoped to the subagent's execution and automatically cleaned up.

Triggers

This skill activates when users want to:

• Create a new sub-agent or custom agent for Claude Code
• Configure task-specific AI workflows with specialized prompts
• Set up automatic delegation for specific task types
• Customize tool access or permission modes for agents
• Build specialized assistants (code reviewer, debugger)

Extension Points

1. Template customization: Modify assets/subagent-template.md to match organizational standards or add custom fields
2. Permission mode additions: Extend references/permission-modes.md with organization-specific permission configurations
3. Example library: Add new sub-agent examples to references/examples.md
4. Tool configurations: Create preset tool combinations for agent types

Anti-Patterns

Avoid these common mistakes when creating sub-agents:

• Overly broad descriptions: Vague descriptions prevent auto-delegation
• Missing proactive trigger: Forgetting "use proactively" in description
• Excessive tool restrictions: Over-restricting when agent needs flexibility
• Monolithic prompts: Long system prompts instead of focused, concise ones
• Hardcoded paths: Including absolute paths or env-specific values
• Ignoring permission modes: Not using permissionMode for elevated access

Design Rationale

Why YAML frontmatter? Provides structured, parseable configuration while keeping the system prompt in readable Markdown. Matches skill format.

Why description is critical? The Task tool uses descriptions to determine which sub-agent to delegate to. Descriptions are the primary routing mechanism.

Why optional tools field? Most sub-agents benefit from full tool access. Restricting is only needed for security-sensitive or read-only tasks.

Why permission modes? Different tasks require different trust levels. A code reviewer needs only read access, while an auto-fixer needs edit. Permission modes enable safe automation without blanket approvals.