Agent Development

Overview

Agents are autonomous AI specialists defined as markdown files with YAML frontmatter and system prompt body.

Agent File Structure

---
name: my-agent
description: Use this agent when... with 2-4 triggering examples
model: inherit
color: blue
tools: Tool1, Tool2
---

System prompt instructions here.

Required Fields

Field	Description
name	Lowercase identifier (3-50 chars, hyphens only)
description	"Use this agent when..." with triggering conditions

Optional Fields

Field	Description
model	inherit, sonnet, opus, or haiku
color	Visual identifier: blue, cyan, green, yellow, magenta, red
tools	Array restricting tool access

System Prompt Design

Use second-person language in the markdown body:

You are a [role] specialized in [domain].

## Process
1. First, analyze...
2. Then, evaluate...
3. Finally, provide...

## Output Format
Structure your response as...

## Quality Standards
Ensure all outputs...

Prompt Guidelines

• Keep between 500-3,000 characters
• Define clear role and responsibilities
• Provide step-by-step analysis process
• Specify output format
• Include quality standards and edge cases

Description Field (Critical)

The description teaches Claude when to activate the agent:

description: |
  Use this agent when reviewing code changes for quality and security.
  Examples:
  - User asks "review my PR" → triggers because code review requested
  - User commits changes and wants feedback → triggers for post-commit review
  - User mentions security concerns in code → triggers for security-focused review

Best Practices

1. Principle of least privilege - Restrict tools to minimum needed
2. Consistent colors - Use same color for similar agent types
3. Test triggering - Verify agent activates for intended scenarios
4. Clear boundaries - Define what agent does NOT do

File Location

.claude/agents/my-agent.md      # Project scope
~/.claude/agents/my-agent.md    # User scope
plugin/agents/my-agent.md       # Plugin scope