# Agent Configuration Guide

Complete reference for configuring Claude Code sub-agents.

## File Format

Agents are markdown files with YAML frontmatter:

```markdown
---
name: agent-name
description: When to use this agent
tools: Read, Edit, Bash
model: sonnet
---

# System Prompt

Agent instructions here...
```

## Configuration Fields

### name (Required)

**Type**: String
**Format**: Lowercase with hyphens
**Example**: `code-reviewer`, `sql-analyst`, `bug-hunter`

**Rules**:
- Use descriptive, action-oriented names
- Avoid generic names like "helper" or "assistant"
- Must be unique within scope (project or user)

**Good Examples**:
- `rails-code-reviewer`
- `security-auditor`
- `performance-analyzer`

**Bad Examples**:
- `MyAgent` (not lowercase-with-hyphens)
- `helper` (too generic)
- `agent1` (not descriptive)

### description (Required)

**Type**: String
**Purpose**: Tells Claude when to invoke this agent

**Best Practices**:
- Start with action phrase: "Use this agent when...", "Analyze X to Y", "Review Z for..."
- Include specific trigger keywords
- Use "PROACTIVELY" or "MUST BE USED" for automatic invocation
- Describe the task, not the agent

**Examples**:

```yaml
# Good: Specific triggers
description: Use PROACTIVELY to review Rails code changes for style violations, security issues, and performance problems

# Good: Clear use case
description: Analyze SQL queries for performance bottlenecks and suggest optimizations using EXPLAIN plans

# Bad: Too generic
description: A helpful agent for code tasks

# Bad: Describes agent, not task
description: An expert programmer who knows many languages
```

### tools (Optional)

**Type**: Comma-separated string
**Default**: Inherits all tools from main conversation

**Available Tools**:
- `Read` - Read files
- `Write` - Create new files
- `Edit` - Modify existing files
- `Bash` - Execute shell commands
- `Grep` - Search file contents
- `Glob` - Find files by pattern
- MCP server tools (if installed)

**Examples**:

```yaml
# Read-only agent
tools: Read, Grep, Glob

# Code modifier
tools: Read, Edit, Bash

# Full access
tools: Read, Write, Edit, Bash, Grep, Glob

# No tools specified = inherit all
# (omit the tools field)
```

**When to Limit Tools**:
- Security-sensitive agents (e.g., only Read for auditing)
- Prevent accidental modifications (exclude Write/Edit)
- Focused agents (e.g., only Grep for searching)

### model (Optional)

**Type**: String
**Default**: `inherit` (uses main conversation model)

**Options**:
- `sonnet` - Claude Sonnet (balanced performance)
- `opus` - Claude Opus (highest capability)
- `haiku` - Claude Haiku (fastest, most economical)
- `inherit` - Use main conversation's model

**Examples**:

```yaml
# Use faster model for simple tasks
model: haiku

# Use most capable model for complex analysis
model: opus

# Default to main conversation model
model: inherit

# Omit field to inherit
# (no model field = inherit)
```

**When to Specify**:
- Use `haiku` for simple, repetitive tasks (fast + cheap)
- Use `opus` for complex reasoning or critical decisions
- Use `sonnet` for balanced performance (default recommended)

## System Prompt Guidelines

The markdown body after frontmatter is the agent's system prompt.

### Structure

```markdown
---
name: my-agent
description: Agent description here
---

# Agent Purpose

High-level overview of what this agent does.

## Core Responsibilities

1. Responsibility 1
2. Responsibility 2
3. Responsibility 3

## Approach

How the agent should approach tasks:
- Step 1: What to do first
- Step 2: How to analyze
- Step 3: What to output

## Output Format

Expected output structure:
- Format specifications
- Required sections
- Example outputs

## Constraints

What the agent should NOT do:
- Constraint 1
- Constraint 2

## Examples

### Example 1: [Scenario]
**Input**: [Example input]
**Output**: [Expected output]

### Example 2: [Another scenario]
...
```

### Best Practices

1. **Be Specific**: Detailed instructions yield better results
2. **Include Examples**: Show the agent what good outputs look like
3. **Set Constraints**: Explicitly state what NOT to do
4. **Define Output Format**: Specify structure and style
5. **Break Down Steps**: Guide the agent's reasoning process

### Good System Prompt Example

```markdown
---
name: test-failure-analyzer
description: Use when tests fail to identify root cause and suggest fixes
tools: Read, Grep, Bash
model: sonnet
---

# Test Failure Analyzer

Systematically analyze test failures to identify root causes and propose fixes.

## Core Responsibilities

1. Read test output to identify failing tests
2. Examine test code and implementation
3. Identify the root cause (not just symptoms)
4. Propose specific, minimal fixes
5. Suggest additional test cases if needed

## Analysis Approach

### Step 1: Gather Context
- Read the full test output
- Identify all failing test names
- Note error messages and stack traces

### Step 2: Examine Code
- Read failing test file
- Read implementation being tested
- Identify the assertion that failed

### Step 3: Root Cause Analysis
- Determine if it's a test issue or implementation bug
- Check for timing issues, environment dependencies
- Look for recent changes that might have caused it

### Step 4: Propose Fix
- Suggest minimal code change
- Explain why this fixes the root cause
- Note any side effects or risks

## Output Format

```
## Test Failure Analysis

**Failing Tests**: [List of test names]

**Root Cause**: [One-sentence summary]

**Details**: [Explanation of why tests are failing]

**Proposed Fix**:
[Specific code changes]

**Reasoning**: [Why this fix addresses root cause]

**Risks**: [Any potential side effects]
```

## Constraints

- DO NOT modify tests to make them pass if implementation is wrong
- DO NOT propose fixes without understanding root cause
- DO NOT suggest multiple approaches - pick the best one
- DO NOT rewrite large sections - minimal changes only

## Examples

### Example 1: Assertion Failure

**Input**: Test output showing "Expected 5, got 4"

**Analysis**:
1. Read test to see what's being tested
2. Check implementation logic
3. Identify off-by-one error in loop
4. Propose boundary fix

**Output**:
```
Root Cause: Off-by-one error in loop condition
Fix: Change `i < length` to `i <= length` in file.py:42
Reasoning: Loop exits one iteration early
```
```

### Bad System Prompt Example

```markdown
---
name: helper
description: Helps with tasks
---

You are a helpful assistant. Do whatever the user asks.
```

**Problems**:
- Generic name and description won't trigger correctly
- No specific guidance on approach
- No constraints or output format
- No examples

## File Locations

### Project Agents
**Path**: `.claude/agents/` (in project root)
**Scope**: Available only in this project
**Version Control**: Commit to share with team

### User Agents
**Path**: `~/.claude/agents/` (in home directory)
**Scope**: Available in all projects
**Version Control**: Personal, not shared

### Priority
Project agents override user agents with the same name.

## Validation Checklist

Before deploying your agent, verify:

- [ ] Name is lowercase-with-hyphens
- [ ] Name is descriptive (not generic)
- [ ] Description includes specific trigger conditions
- [ ] Description uses action-oriented language
- [ ] Tools are limited to what's needed (or omitted for full access)
- [ ] Model is appropriate for task complexity (or omitted to inherit)
- [ ] System prompt is detailed and specific
- [ ] Output format is clearly defined
- [ ] Examples are included
- [ ] Constraints are explicit
- [ ] File is in correct location (.claude/agents/ or ~/.claude/agents/)
- [ ] YAML frontmatter is valid

## Common Issues

### Agent Never Triggers
- Description too generic
- Missing trigger keywords
- Name conflicts with another agent

**Fix**: Add specific keywords to description, use "PROACTIVELY" or "MUST BE USED"

### Agent Has Wrong Permissions
- Tools not specified correctly
- Typo in tool names

**Fix**: Check available tool names, use comma-separated list

### Agent Produces Wrong Outputs
- System prompt too vague
- Missing examples
- No output format specified

**Fix**: Add detailed instructions, examples, and explicit output format

### Agent Not Found
- Wrong file location
- File naming issue

**Fix**: Ensure file is in `.claude/agents/` (project) or `~/.claude/agents/` (user)

---

**Related**:
- [Agent Examples](./agent-examples.md)
- [Best Practices](./best-practices.md)
- [Troubleshooting](./troubleshooting.md)