| name | agent-development |
| description | This skill guides creating autonomous agents for Claude Code plugins using markdown files with YAML frontmatter. Use when building new agents, designing agent system prompts, or configuring agent behavior. |
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
