Agent Development

•

24.4k23983 months ago

This skill should be used when the user asks to "create an agent", "add an agent", "write a subagent", "agent frontmatter", "when to use description", "agent examples", "agent tools", "agent colors", "autonomous agent", or needs guidance on agent structure, system prompts, triggering conditions, or agent development best practices for Claude Code plugins.

Quick Install

npxskills add davila7/claude-code-templates--skill "Agent Development"

Instructions

Agent Development for Claude Code Plugins

Overview

Agents are autonomous subprocesses that handle complex, multi-step tasks independently. Understanding agent structure, triggering conditions, and system prompt design enables creating powerful autonomous capabilities.

Key concepts:

Agents are FOR autonomous work, commands are FOR user-initiated actions
Markdown file format with YAML frontmatter
Triggering via description field with examples
System prompt defines agent behavior
Model and color customization

Agent File Structure

Complete Format

---
name: agent-identifier
description: Use this agent when [triggering conditions]. Examples:

<example>
Context: [Situation description]
user: "[User request]"
assistant: "[How assistant should respond and use this agent]"
<commentary>
[Why this agent should be triggered]
</commentary>
</example>

<example>
[Additional example...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [agent role description]...

**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]

**Analysis Process:**
[Step-by-step workflow]

**Output Format:**
[What to return]

Frontmatter Fields

name (required)

Agent identifier used for namespacing and invocation.

Format: lowercase, numbers, hyphens only Length: 3-50 characters Pattern: Must start and end with alphanumeric

Good examples:

code-reviewer
test-generator
api-docs-writer
security-analyzer

Bad examples:

helper (too generic)
-agent- (starts/ends with hyphen)
my_agent (underscores not allowed)
ag (too short, < 3 chars)

description (required)

Defines when Claude should trigger this agent. This is the most critical field.

Must include:

Triggering conditions ("Use this agent when...")
Multiple <example> blocks showing usage
Context, user request, and assistant response in each example
<commentary> explaining why agent triggers

Format:

Use this agent when [conditions]. Examples:

<example>
Context: [Scenario description]
user: "[What user says]"
assistant: "[How Claude should respond]"
<commentary>
[Why this agent is appropriate]
</commentary>
</example>

[More examples...]

Best practices:

Include 2-4 concrete examples
Show proactive and reactive triggering
Cover different phrasings of same intent
Explain reasoning in commentary
Be specific about when NOT to use the agent

model (required)

Which model the agent should use.

Options:

inherit - Use same model as parent (recommended)
sonnet - Claude Sonnet (balanced)
opus - Claude Opus (most capable, expensive)
haiku - Claude Haiku (fast, cheap)

Recommendation: Use inherit unless agent needs specific model capabilities.

color (required)

Visual identifier for agent in UI.

Options: blue, cyan, green, yellow, magenta, red

Guidelines:

Choose distinct colors for different agents in same plugin
Use consistent colors for similar agent types
Blue/cyan: Analysis, review
Green: Success-oriented tasks
Yellow: Caution, validation
Red: Critical, security
Magenta: Creative, generation

tools (optional)

Restrict agent to specific tools.

Format: Array of tool names

tools: ["Read", "Write", "Grep", "Bash"]

Default: If omitted, agent has access to all tools

Best practice: Limit tools to minimum needed (principle of least privilege)

Common tool sets:

Read-only analysis: ["Read", "Grep", "Glob"]
Code generation: ["Read", "Write", "Grep"]
Testing: ["Read", "Bash", "Grep"]
Full access: Omit field or use ["*"]

System Prompt Design

The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.

Structure

Standard template:

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities...]

**Analysis Process:**
1. [Step one]
2. [Step two]
3. [Step three]
[...]

**Quality Standards:**
- [Standard 1]
- [Standard 2]

**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]

**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]

Best Practices

✅ DO:

Write in second person ("You are...", "You will...")
Be specific about responsibilities
Provide step-by-step process
Define output format
Include quality standards
Address edge cases
Keep under 10,000 characters

❌ DON'T:

Write in first person ("I am...", "I will...")
Be vague or generic
Omit process steps
Leave output format undefined
Skip quality guidance
Ignore error cases

Creating Agents

Method 1: AI-Assisted Generation

Use this prompt pattern (extracted from Claude Code):

Create an agent configuration based on this request: "[YOUR DESCRIPTION]"

Requirements:
1. Extract core intent and responsibilities
2. Design expert persona for the domain
3. Create comprehensive system prompt with:
   - Clear behavioral boundaries
   - Specific methodologies
   - Edge case handling
   - Output format
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions
6. Include 2-3 <example> blocks showing when to use

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Examples: <example>...</example>",
  "systemPrompt": "You are..."
}

Then convert to agent file format with frontmatter.

See examples/agent-creation-prompt.md for complete template.

Method 2: Manual Creation

Choose agent identifier (3-50 chars, lowercase, hyphens)
Write description with examples
Select model (usually inherit)
Choose color for visual identification
Define tools (if restricting access)
Write system prompt with structure above
Save as agents/agent-name.md

Validation Rules

Identifier Validation

✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)

Rules:

3-50 characters
Lowercase letters, numbers, hyphens only
Must start and end with alphanumeric
No underscores, spaces, or special characters

Description Validation

Length: 10-5,000 characters Must include: Triggering conditions and examples Best: 200-1,000 characters with 2-4 examples

System Prompt Validation

Length: 20-10,000 characters Best: 500-3,000 characters Structure: Clear responsibilities, process, output format

Agent Organization

Plugin Agents Directory

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

All .md files in agents/ are auto-discovered.

Namespacing

Agents are namespaced automatically:

Single plugin: agent-name
With subdirectories: plugin:subdir:agent-name

Testing Agents

Test Triggering

Create test scenarios to verify agent triggers correctly:

Write agent with specific triggering examples
Use similar phrasing to examples in test
Check Claude loads the agent
Verify agent provides expected functionality

Test System Prompt

Ensure system prompt is complete:

Give agent typical task
Check it follows process steps
Verify output format is correct
Test edge cases mentioned in prompt
Confirm quality standards are met

Quick Reference

Minimal Agent

---
name: simple-agent
description: Use this agent when... Examples: <example>...</example>
model: inherit
color: blue
---

You are an agent that [does X].

Process:
1. [Step 1]
2. [Step 2]

Output: [What to provide]

Frontmatter Fields Summary

Field	Required	Format	Example
name	Yes	lowercase-hyphens	code-reviewer
description	Yes	Text + examples	Use when... <example>...
model	Yes	inherit/sonnet/opus/haiku	inherit
color	Yes	Color name	blue
tools	No	Array of tool names	["Read", "Grep"]

Best Practices

DO:

✅ Include 2-4 concrete examples in description
✅ Write specific triggering conditions
✅ Use inherit for model unless specific need
✅ Choose appropriate tools (least privilege)
✅ Write clear, structured system prompts
✅ Test agent triggering thoroughly

DON'T:

❌ Use generic descriptions without examples
❌ Omit triggering conditions
❌ Give all agents same color
❌ Grant unnecessary tool access
❌ Write vague system prompts
❌ Skip testing

Additional Resources

Reference Files

For detailed guidance, consult:

references/system-prompt-design.md - Complete system prompt patterns
references/triggering-examples.md - Example formats and best practices
references/agent-creation-system-prompt.md - The exact prompt from Claude Code

Example Files

Working examples in examples/:

agent-creation-prompt.md - AI-assisted agent generation template
complete-agent-examples.md - Full agent examples for different use cases

Utility Scripts

Development tools in scripts/:

validate-agent.sh - Validate agent file structure
test-agent-trigger.sh - Test if agent triggers correctly

Implementation Workflow

To create an agent for a plugin:

Define agent purpose and triggering conditions
Choose creation method (AI-assisted or manual)
Create agents/agent-name.md file
Write frontmatter with all required fields
Write system prompt following best practices
Include 2-4 triggering examples in description
Validate with scripts/validate-agent.sh
Test triggering with real scenarios
Document agent in plugin README

Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.

Loading…

Related Skills

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,360

coding-agent

Run Codex CLI, Claude Code, OpenCode, or Pi Coding Agent via background process for programmatic control.

359,326

skill-creator

Create or update AgentSkills. Use when designing, structuring, or packaging skills with scripts, references, and assets.

367,309

1password

Set up and use 1Password CLI (op). Use when installing the CLI, enabling desktop app integration, signing in (single or multi-account), or reading/injecting/running secrets via op.

365,915

Tags & Topics

anthropicanthropic-claudeclaudeclaude-code

Agent Development for Claude Code Plugins

Overview

Key concepts:

Agents are FOR autonomous work, commands are FOR user-initiated actions
Markdown file format with YAML frontmatter
Triggering via description field with examples
System prompt defines agent behavior
Model and color customization

Agent File Structure

Complete Format

---
name: agent-identifier
description: Use this agent when [triggering conditions]. Examples:

<example>
Context: [Situation description]
user: "[User request]"
assistant: "[How assistant should respond and use this agent]"
<commentary>
[Why this agent should be triggered]
</commentary>
</example>

<example>
[Additional example...]
</example>

model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---

You are [agent role description]...

**Your Core Responsibilities:**
1. [Responsibility 1]
2. [Responsibility 2]

**Analysis Process:**
[Step-by-step workflow]

**Output Format:**
[What to return]

Frontmatter Fields

name (required)

Agent identifier used for namespacing and invocation.

Format: lowercase, numbers, hyphens only Length: 3-50 characters Pattern: Must start and end with alphanumeric

Good examples:

code-reviewer
test-generator
api-docs-writer
security-analyzer

Bad examples:

helper (too generic)
-agent- (starts/ends with hyphen)
my_agent (underscores not allowed)
ag (too short, < 3 chars)

description (required)

Defines when Claude should trigger this agent. This is the most critical field.

Must include:

Triggering conditions ("Use this agent when...")
Multiple <example> blocks showing usage
Context, user request, and assistant response in each example
<commentary> explaining why agent triggers

Format:

Use this agent when [conditions]. Examples:

<example>
Context: [Scenario description]
user: "[What user says]"
assistant: "[How Claude should respond]"
<commentary>
[Why this agent is appropriate]
</commentary>
</example>

[More examples...]

Best practices:

Include 2-4 concrete examples
Show proactive and reactive triggering
Cover different phrasings of same intent
Explain reasoning in commentary
Be specific about when NOT to use the agent

model (required)

Which model the agent should use.

Options:

inherit - Use same model as parent (recommended)
sonnet - Claude Sonnet (balanced)
opus - Claude Opus (most capable, expensive)
haiku - Claude Haiku (fast, cheap)

Recommendation: Use inherit unless agent needs specific model capabilities.

color (required)

Visual identifier for agent in UI.

Options: blue, cyan, green, yellow, magenta, red

Guidelines:

Choose distinct colors for different agents in same plugin
Use consistent colors for similar agent types
Blue/cyan: Analysis, review
Green: Success-oriented tasks
Yellow: Caution, validation
Red: Critical, security
Magenta: Creative, generation

tools (optional)

Restrict agent to specific tools.

Format: Array of tool names

tools: ["Read", "Write", "Grep", "Bash"]

Default: If omitted, agent has access to all tools

Best practice: Limit tools to minimum needed (principle of least privilege)

Common tool sets:

Read-only analysis: ["Read", "Grep", "Glob"]
Code generation: ["Read", "Write", "Grep"]
Testing: ["Read", "Bash", "Grep"]
Full access: Omit field or use ["*"]

System Prompt Design

The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.

Structure

Standard template:

You are [role] specializing in [domain].

**Your Core Responsibilities:**
1. [Primary responsibility]
2. [Secondary responsibility]
3. [Additional responsibilities...]

**Analysis Process:**
1. [Step one]
2. [Step two]
3. [Step three]
[...]

**Quality Standards:**
- [Standard 1]
- [Standard 2]

**Output Format:**
Provide results in this format:
- [What to include]
- [How to structure]

**Edge Cases:**
Handle these situations:
- [Edge case 1]: [How to handle]
- [Edge case 2]: [How to handle]

Best Practices

✅ DO:

Write in second person ("You are...", "You will...")
Be specific about responsibilities
Provide step-by-step process
Define output format
Include quality standards
Address edge cases
Keep under 10,000 characters

❌ DON'T:

Write in first person ("I am...", "I will...")
Be vague or generic
Omit process steps
Leave output format undefined
Skip quality guidance
Ignore error cases

Creating Agents

Method 1: AI-Assisted Generation

Use this prompt pattern (extracted from Claude Code):

Create an agent configuration based on this request: "[YOUR DESCRIPTION]"

Requirements:
1. Extract core intent and responsibilities
2. Design expert persona for the domain
3. Create comprehensive system prompt with:
   - Clear behavioral boundaries
   - Specific methodologies
   - Edge case handling
   - Output format
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions
6. Include 2-3 <example> blocks showing when to use

Return JSON with:
{
  "identifier": "agent-name",
  "whenToUse": "Use this agent when... Examples: <example>...</example>",
  "systemPrompt": "You are..."
}

Then convert to agent file format with frontmatter.

See examples/agent-creation-prompt.md for complete template.

Method 2: Manual Creation

Choose agent identifier (3-50 chars, lowercase, hyphens)
Write description with examples
Select model (usually inherit)
Choose color for visual identification
Define tools (if restricting access)
Write system prompt with structure above
Save as agents/agent-name.md

Validation Rules

Identifier Validation

✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)

Rules:

3-50 characters
Lowercase letters, numbers, hyphens only
Must start and end with alphanumeric
No underscores, spaces, or special characters

Description Validation

Length: 10-5,000 characters Must include: Triggering conditions and examples Best: 200-1,000 characters with 2-4 examples

System Prompt Validation

Length: 20-10,000 characters Best: 500-3,000 characters Structure: Clear responsibilities, process, output format

Agent Organization

Plugin Agents Directory

plugin-name/
└── agents/
    ├── analyzer.md
    ├── reviewer.md
    └── generator.md

All .md files in agents/ are auto-discovered.

Namespacing

Agents are namespaced automatically:

Single plugin: agent-name
With subdirectories: plugin:subdir:agent-name

Testing Agents

Test Triggering

Create test scenarios to verify agent triggers correctly:

Write agent with specific triggering examples
Use similar phrasing to examples in test
Check Claude loads the agent
Verify agent provides expected functionality

Test System Prompt

Ensure system prompt is complete:

Give agent typical task
Check it follows process steps
Verify output format is correct
Test edge cases mentioned in prompt
Confirm quality standards are met

Quick Reference

Minimal Agent

---
name: simple-agent
description: Use this agent when... Examples: <example>...</example>
model: inherit
color: blue
---

You are an agent that [does X].

Process:
1. [Step 1]
2. [Step 2]

Output: [What to provide]

Frontmatter Fields Summary

Field	Required	Format	Example
name	Yes	lowercase-hyphens	code-reviewer
description	Yes	Text + examples	Use when... <example>...
model	Yes	inherit/sonnet/opus/haiku	inherit
color	Yes	Color name	blue
tools	No	Array of tool names	["Read", "Grep"]

Best Practices

DO:

✅ Include 2-4 concrete examples in description
✅ Write specific triggering conditions
✅ Use inherit for model unless specific need
✅ Choose appropriate tools (least privilege)
✅ Write clear, structured system prompts
✅ Test agent triggering thoroughly

DON'T:

❌ Use generic descriptions without examples
❌ Omit triggering conditions
❌ Give all agents same color
❌ Grant unnecessary tool access
❌ Write vague system prompts
❌ Skip testing

Additional Resources

Reference Files

For detailed guidance, consult:

references/system-prompt-design.md - Complete system prompt patterns
references/triggering-examples.md - Example formats and best practices
references/agent-creation-system-prompt.md - The exact prompt from Claude Code

Example Files

Working examples in examples/:

agent-creation-prompt.md - AI-assisted agent generation template
complete-agent-examples.md - Full agent examples for different use cases

Utility Scripts

Development tools in scripts/:

validate-agent.sh - Validate agent file structure
test-agent-trigger.sh - Test if agent triggers correctly

Implementation Workflow

To create an agent for a plugin:

Define agent purpose and triggering conditions
Choose creation method (AI-assisted or manual)
Create agents/agent-name.md file
Write frontmatter with all required fields
Write system prompt following best practices
Include 2-4 triggering examples in description
Validate with scripts/validate-agent.sh
Test triggering with real scenarios
Document agent in plugin README

Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.