agent-development

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

```markdown

---

name: my-agent

description: Use this agent when... with 2-4 triggering examples

model: inherit

color: blue

tools: Tool1, Tool2

---

System prompt instructions here.

```

| Field | Description |

|-------|-------------|

| name | Lowercase identifier (3-50 chars, hyphens only) |

| description | "Use this agent when..." with triggering conditions |

| Field | Description |

|-------|-------------|

| model | inherit, sonnet, opus, or haiku |

| color | Visual identifier: blue, cyan, green, yellow, magenta, red |

| tools | Array restricting tool access |

Use second-person language in the markdown body:

```markdown

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

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

Structure your response as...

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

The description teaches Claude when to activate the agent:

```yaml

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

```

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

```

.claude/agents/my-agent.md # Project scope

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

plugin/agents/my-agent.md # Plugin scope

```