s-hiraoku 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
- Principle of least privilege - Restrict tools to minimum needed
- Consistent colors - Use same color for similar agent types
- Test triggering - Verify agent activates for intended scenarios
- 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