372 lines
8.3 KiB
Markdown
372 lines
8.3 KiB
Markdown
# 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)
|