---
name: agent-builder
description: Create Claude Code subagents with proper frontmatter, tool access, and delegation semantics. Use when creating new agents, fixing agent configuration, or building specialized task executors. Agents are delegated workers that receive full context and execute without user interaction.
---

# Agent Builder

Build specialized AI subagents for Claude Code that handle task-specific workflows via delegation.

## When to Use

- Creating new subagents for specialized tasks
- Fixing agent frontmatter or tool configuration
- Building builder agents that invoke skills
- Converting workflows into delegated executors
- Standardizing team agent patterns

## Critical Understanding: Agents vs Skills vs Commands

**Agents (Subagents)**:
- Separate context windows
- **Delegated execution**: Receive full context, execute, return results (NO user interaction mid-task)
- Explicitly or automatically invoked based on description
- Example: "Use the code-reviewer agent to check this PR"

**Skills**:
- Model-invoked: Claude autonomously decides when to use based on description
- Operate in active context (main conversation or agent's context)
- Loaded progressively via Skill tool
- Example: Agent invokes "pdf-processing" skill for guidance

**Slash Commands**:
- User-invoked: Explicitly typed `/command` to trigger
- Expand to prompts in conversation
- Example: `/commit` to create git commit

**Key Difference**: Agents are **task executors** (do the work), Skills are **knowledge bases** (provide guidance), Commands are **prompt templates** (expand instructions).

## Quick Start Workflow

### 1. Choose Agent Location

**Project agents** (shared with team via git):
```bash
.claude/agents/<agent-name>.md
```

**Personal agents** (available across all projects):
```bash
~/.claude/agents/<agent-name>.md
```

**Plugin agents** (distributed via marketplace):
```bash
plugins/<plugin-name>/agents/<agent-name>.md
```

### 2. Create Agent File

Agent files are Markdown with YAML frontmatter:

```markdown
---
name: your-agent-name
description: When to delegate this task. Be specific about triggers and use cases.
tools: Tool1, Tool2, Tool3
model: sonnet
---

# Agent Name

You are a [specialized role]. You [do specific task] by:

1. [Step 1 - often invoking a skill for guidance]
2. [Step 2 - gathering context]
3. [Step 3 - executing core task]
4. [Step 4 - validating output]
5. [Return results to main conversation]

## Critical Rules

- No user interaction mid-execution (you receive complete context upfront)
- Execute deterministically based on provided context
- Return clear results or errors

[Additional instructions specific to this agent's domain]
```

### 3. Test Invocation

**Explicit delegation**:
```
Use the code-reviewer agent to analyze src/auth.ts
```

**Automatic delegation** (if description matches context):
```
description: "Code review specialist. Use proactively after code changes."
```

Check `/agents` to verify agent appears.

## Essential Patterns

### Pattern 1: Basic Agent (No Skill Invocation)

```markdown
---
name: code-formatter
description: Format code files according to project standards. Use when user requests code formatting.
tools: Read, Write, Edit, Bash
model: sonnet
---

# Code Formatter

You format code files by:

1. Reading the target file
2. Detecting the language and format style
3. Running appropriate formatter (prettier, black, rustfmt)
4. Writing formatted code back
5. Reporting changes made

Execute without asking questions - you have full context.
```

**Invocation**: "Use code-formatter agent on src/index.ts"

### Pattern 2: Builder Agent (Invokes Skill for Guidance)

```markdown
---
name: slash-command-builder-agent
description: Creates Claude Code slash commands by invoking slash-command-builder skill. Use when user wants to create a new slash command.
tools: Skill, Read, Write, Edit, Grep
model: sonnet
---

# Slash Command Builder Agent

You create slash commands by:

1. **Invoke slash-command-builder skill** for patterns and validation rules
   - Use Skill tool: `command: "slash-command-builder"`
   - Read the guidance on frontmatter, arguments, bash integration

2. **Gather requirements** from delegated context:
   - Command name
   - Description
   - Arguments (if any)
   - Bash execution needs (if any)
   - Tool permissions

3. **Generate command file**:
   - Create .md file with proper frontmatter
   - Add YAML fields (description, argument-hint, allowed-tools)
   - Write command body using $ARGUMENTS syntax

4. **Validate syntax**:
   - Check YAML frontmatter is valid
   - Verify argument placeholders use $ARGUMENTS or $1, $2, etc.
   - Ensure description is present

5. **Return results** with file path and validation status

## Critical Rules

- Always invoke slash-command-builder skill first for current patterns
- Use shell-style $ARGUMENTS, NOT template-style {{ARGUMENTS}}
- Validate frontmatter before returning
- No user questions - execute based on delegated context
```

**Invocation**: "Use slash-command-builder-agent to create /review-pr command that takes pr-number and priority"

### Pattern 3: Validator Agent (References Production Examples)

```markdown
---
name: effect-pattern-validator-agent
description: Validates Effect.ts code against production patterns by invoking effect-pattern-validator skill. Use when reviewing Effect code.
tools: Skill, Read, Grep, Glob
model: sonnet
---

# Effect Pattern Validator Agent

You validate Effect code by:

1. **Invoke effect-pattern-validator skill** for production patterns
2. **Read target code** files
3. **Compare against production examples** from skill's reference repos
4. **Report deviations** with specific file references
5. **Suggest corrections** using production patterns

No user interaction - you have the code context to validate.
```

## Frontmatter Fields Reference

### Required Fields

**name** (required):
```yaml
name: your-agent-name
```
- Lowercase letters, numbers, hyphens only
- Used for invocation: "use the your-agent-name agent"

**description** (required):
```yaml
description: When to delegate this task. Be specific about triggers.
```
- Critical for automatic delegation
- Include what agent does AND when to use it
- Mention key terms that would appear in user requests

### Optional Fields

**tools** (optional, inherits all if omitted):
```yaml
tools: Skill, Read, Write, Edit, Bash, Grep
```
- **If omitted**: Agent inherits ALL tools from main thread (including MCP tools)
- **If specified**: Agent ONLY has listed tools (must be explicit)
- **Critical**: Include `Skill` tool if agent needs to invoke skills

**model** (optional):
```yaml
model: sonnet      # Use alias
model: inherit     # Use main conversation's model
```
- Defaults to sonnet if omitted
- Use `inherit` for consistency with main conversation

## Tool Access Patterns

### When to Grant Skill Tool

**Grant `Skill` tool when**:
- Agent invokes builder skills for guidance (slash-command-builder, hook-builder, etc.)
- Agent needs domain knowledge from skills (pdf-processing, excel-analysis, etc.)
- Agent validates patterns using skill references

**Example**:
```yaml
tools: Skill, Read, Write, Edit
```

Agent can invoke: `Skill({ command: "slash-command-builder" })`

### When to Omit Tools Field

**Omit `tools` field when**:
- Agent needs maximum flexibility
- You want to inherit all MCP tools
- Agent's tasks are unpredictable

**Example**:
```yaml
name: general-researcher
description: Research any topic using all available tools
# tools field omitted - inherits everything
```

### Common Tool Combinations

**Builder agents**:
```yaml
tools: Skill, Read, Write, Edit, Grep, Glob
```

**Validator agents**:
```yaml
tools: Skill, Read, Grep, Glob
```

**Formatter agents**:
```yaml
tools: Read, Write, Edit, Bash
```

**Research agents**:
```yaml
# Omit tools to inherit all including MCP tools
```

## Delegation Semantics

### One-Shot Execution

Agents receive full context from delegating conversation and execute without back-and-forth:

**Main Claude**:
```
Use slash-command-builder-agent to create a /review-pr command that:
- Takes two arguments: pr-number and priority
- Uses gh CLI to fetch PR details
- Outputs structured review checklist
```

**Agent receives**:
- Complete specification above
- Current working directory context
- Available tools

**Agent executes**:
1. Invokes slash-command-builder skill
2. Generates command file with frontmatter
3. Validates syntax
4. Returns file path + status

**Agent returns** to main Claude:
```
Created /review-pr command at .claude/commands/review-pr.md

Frontmatter:
- description: Review pull request with priority
- argument-hint: [pr-number] [priority]
- allowed-tools: Bash(gh:*)

Validation: ✅ YAML valid, arguments use $1 and $2 syntax
```

### No User Interaction

**❌ Wrong** (agent asks questions):
```markdown
You create commands by:
1. Ask user for command name
2. Ask user for description
3. Generate file
```

**✅ Correct** (agent uses delegated context):
```markdown
You create commands by:
1. Extract requirements from delegated context
2. Invoke skill for validation patterns
3. Generate file using provided spec
4. Return results
```

## File Locations and Priority

### Location Priority

When agent names conflict, priority is:
1. **Project agents** (`.claude/agents/`) - Highest priority
2. **CLI-defined agents** (`--agents` flag)
3. **User agents** (`~/.claude/agents/`)
4. **Plugin agents** (from installed plugins)

### Plugin Agents

Agents in plugins load from:
```
plugins/<plugin-name>/agents/<agent-name>.md
```

Plugin agents:
- Appear in `/agents` interface
- Can be invoked like user/project agents
- Distributed via marketplace

## Testing Workflow

1. **Create agent file** with proper frontmatter
2. **Restart Claude Code** (or start new conversation)
3. **Check `/agents`** - verify agent appears in list
4. **Explicit test**: "Use the agent-name agent to [task]"
5. **Verify behavior**: Check agent executes without asking questions
6. **Validate output**: Ensure agent returns clear results

## Common Issues & Fixes

### Issue: Agent Asks Questions During Execution

❌ **Wrong pattern**:
```markdown
You create hooks by:
1. Ask user which event type they want
2. Ask for the hook name
```

✅ **Correct pattern**:
```markdown
You create hooks by:
1. Extract event type from delegated context
2. Extract hook name from delegated context
3. If context is incomplete, return error with missing requirements
```

**Why**: Agents can't interact with users mid-execution.

### Issue: Agent Not Using Skill

❌ **Missing Skill tool**:
```yaml
tools: Read, Write, Edit
# Skill tool not granted!
```

✅ **Include Skill tool**:
```yaml
tools: Skill, Read, Write, Edit
```

**Why**: Agents must explicitly have `Skill` tool to invoke skills.

### Issue: Agent Not Found in `/agents`

**Check**:
- File location correct? (`.claude/agents/` or `~/.claude/agents/`)
- YAML frontmatter valid?
- Name field present and properly formatted?

**Fix**:
```bash
# Verify file exists
ls .claude/agents/

# Check YAML syntax
head -n 10 .claude/agents/my-agent.md

# Restart Claude Code to reload agents
```

### Issue: Tools Field vs Inheritance Confusion

**If you want maximum tools**:
```yaml
# Omit tools field entirely
```
Agent inherits ALL tools including future MCP additions.

**If you want restricted tools**:
```yaml
tools: Read, Grep, Glob
# Agent ONLY has these 3 tools
```

## Builder Agent Architecture (Key Pattern)

The builder agent pattern is critical for meta-infrastructure:

```
User: "create a /review-pr command"
  ↓
Main Claude: delegates to slash-command-builder-agent with full spec
  ↓
Agent: invokes slash-command-builder skill via Skill tool
  ↓
Skill: provides frontmatter patterns, argument syntax, examples
  ↓
Agent: generates .md file with proper YAML + body
  ↓
Agent: validates syntax against patterns
  ↓
Agent: returns file + validation status to main Claude
  ↓
Main Claude: shows user the generated command
```

**Why this works**:
- **Skill** = knowledge base (patterns, validation rules, examples)
- **Agent** = executor (reads skill, generates output, validates)
- **Separation** = skills can be improved independently of agents

## Official Documentation

For the complete, up-to-date subagents specification, use the `claude-code-docs-reference` skill or the `claude-code-guide` agent to look up official Anthropic documentation on subagents.

## Improving This Skill

Notice gaps, unclear instructions, or better patterns while using this skill?

Use the `continuous-improvement` skill to propose enhancements:
1. Detect the issue
2. Propose specific changes
3. Git branch → commit → surface for approval
4. Update changelog

This skill should evolve with every use.
