agent-development

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

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