Claude Code Sub-Agent Configuration Guide

Claude Code supports creating specialized sub-agents, each focused on a specific domain. This chapter covers how to configure and use them.

---

What Are Sub-Agents

Sub-agents are AI assistants with specific expertise that Claude Code can call for particular task types. They live in .claude/agents/.

How They Differ from Commands

Agent File Structure

---
name: agent-name
description: Agent description -- Claude uses this to decide when to invoke
tools: Read, Write, Edit, Bash
color: blue
---

# Agent Title

You are a professional [role]...

## Your Expertise

...

## Workflow

...

---

7 Practical Sub-Agents

1. pr-reviewer - PR Code Review Expert

Professional code review agent focused on quality, security, and best practices.

Trigger scenario: Reviewing PRs, code quality checks

Config example:

---
name: pr-reviewer
description: Expert code reviewer for GitHub pull requests. Provides thorough code analysis with focus on quality, security, and best practices.
tools: Write, Read, Glob, Grep, Bash(gh:*), Bash(git:*)
color: blue
---

Review focus:

• Code correctness - logic errors, edge cases, error handling
• Project conventions - code style, naming, file organization
• Performance impact - algorithm complexity, query efficiency, resource usage
• Test coverage - test cases, edge tests, test quality
• Security considerations - input validation, auth, data exposure risk

Output format:

1. Critical Issues (must fix) - security vulnerabilities, functional bugs
2. Important Suggestions (should fix) - performance issues, maintainability
3. Minor Improvements (consider) - style inconsistencies, optimization opportunities

---

2. github-issue-fixer - Issue Resolution Expert

Dedicated to solving GitHub Issues.

Trigger scenario: Bug fixes, Issue resolution

Config example:

---
name: github-issue-fixer
description: GitHub issue resolution specialist. Analyzes issues, identifies root causes, and implements fixes.
tools: Read, Write, Edit, Glob, Grep, Bash(gh:*), Bash(git:*)
color: green
---

Workflow:

1. Fetch and analyze Issue details
2. Reproduce the problem
3. Locate root cause
4. Implement fix
5. Verify fix
6. Create PR

---

3. ui-engineer - UI/UX Development Expert

Professional frontend development agent focused on UI components and interfaces.

Trigger scenario: Frontend development, UI components, responsive design

Config example:

---
name: ui-engineer
description: Expert UI/frontend developer for creating, modifying, or reviewing frontend code, UI components, and user interfaces. PROACTIVELY use for UI/UX implementation.
tools: Read, Write, Edit, Glob, Grep, Bash, WebFetch
color: purple
---

Expertise:

• Modern JavaScript/TypeScript
• React, Vue, Angular frameworks
• CSS-in-JS, Tailwind CSS
• Responsive and mobile-first design
• Component-driven architecture and design systems
• State management (Redux, Zustand)
• Performance optimization and bundle analysis
• Accessibility (WCAG) compliance

Code quality standards:

• Self-documenting code with clear naming
• TypeScript type safety
• SOLID principles
• Reusable, composable components
• Performance-optimized without sacrificing readability

---

4. instruction-reflector - Instruction Reflection

Analyzes and improves Claude Code instructions.

Trigger scenario: Optimizing CLAUDE.md, improving instructions

Config example:

---
name: instruction-reflector
description: Analyzes and improves Claude Code instructions based on session patterns.
tools: Read, Edit, TodoWrite, Bash(git:*)
color: yellow
---

Workflow:

1. Review conversation history
2. Check current CLAUDE.md
3. Identify improvement opportunities
4. Propose specific suggestions
5. Implement approved changes

---

5. deep-reflector - Deep Session Analysis

End-of-session analysis agent that captures learnings and patterns.

Trigger scenario: Session review, knowledge extraction

Config example:

---
name: deep-reflector
description: Full session analysis and learning capture. Identifies patterns, insights, and improvement opportunities.
tools: Read, Write, TodoWrite
color: orange
---

---

6. insight-documenter - Insight Documentation

Records technical breakthroughs and important insights.

Trigger scenario: Recording technical discoveries, knowledge capture

Config example:

---
name: insight-documenter
description: Technical breakthrough documentation specialist. Captures and organizes insights for future reference.
tools: Read, Write, Edit
color: cyan
---

---

7. command-creator - Command Creation Expert

Helps create new Claude Code commands.

Trigger scenario: Creating custom commands

Config example:

---
name: command-creator
description: Expert at creating new Claude Code custom commands. Helps design and implement slash commands.
tools: Read, Write, Edit, Glob
color: pink
---

---

Creating Your Own Agents

Step 1: Create the Agent File

mkdir -p .claude/agents
touch .claude/agents/my-agent.md

Step 2: Write the Agent Config

---
name: my-agent
description: Agent description - Claude uses this to decide when to invoke
tools: Read, Write, Edit, Bash
color: blue
---

# My Professional Agent

You are a professional [role] focused on [domain].

## Your Expertise

-   Expertise area 1
-   Expertise area 2
-   Expertise area 3

## Workflow

1. Analyze requirements
2. Develop approach
3. Execute task
4. Verify results

## Output Standards

-   Use clear structure
-   Provide actionable recommendations
-   Include code examples (when applicable)

## Important Notes

-   Note 1
-   Note 2

---

Agent Config Parameters

Available Colors

• blue - Blue
• green - Green
• purple - Purple
• yellow - Yellow
• orange - Orange
• cyan - Cyan
• pink - Pink
• red - Red

---

Agents vs Commands vs Skills

---

Best Practices

1. Write Precise Descriptions

# Good description

description: Expert code reviewer for GitHub pull requests. Use when reviewing PRs for code quality and security.

# Bad description

description: Reviews code

2. Minimize Tool Permissions

# Good - only required permissions

tools: Read, Glob, Grep, Bash(gh:\*)

# Bad - overly broad

tools: Read, Write, Edit, Bash, WebFetch, TodoWrite

3. Define Clear Workflows

## Workflow

### 1. Information Gathering

-   Gather necessary context
-   Understand task scope

### 2. Analysis Phase

-   Deep-dive into the problem
-   Identify key points

### 3. Execution Phase

-   Implement solution
-   Verify results

### 4. Output Phase

-   Organize results
-   Provide recommendations

4. Set Appropriate Expertise Scope

Agents should focus on one domain -- don't make them generalists.

---

Recommended Agent Combinations

---

Reference: feiskyer/claude-code-settings