Agent Development

What it is

Agent Development is a skill in the plugin-dev plugin. It activates when a user asks to "create an agent", "add an agent", "write a subagent", or asks about agent frontmatter, descriptions, examples, tools, colors or autonomous agents. Agents are autonomous subprocesses that handle complex, multi-step tasks independently. The skill draws a clear line: agents are for autonomous work, while commands are for user-initiated actions. Agents are defined as Markdown files with YAML frontmatter, and the markdown body becomes the agent's system prompt. The skill documents the frontmatter fields in detail. The required name must be 3-50 characters of lowercase letters, numbers and hyphens, and must start and end with an alphanumeric character. The required description is called the most critical field. It defines when Claude should trigger the agent and must include triggering conditions ("Use this agent when...") plus multiple <example> blocks. Each example contains a context, a user request, an assistant response and a <commentary>. The required model field accepts inherit, sonnet, opus or haiku, and inherit is recommended. The required color field accepts blue, cyan, green, yellow, magenta or red, each with suggested meanings. The optional tools field restricts the agent to an array of tool names; if it is omitted, the agent has access to all tools. For system prompts, the skill provides a standard template with these sections: role, core responsibilities, analysis process, quality standards, output format and edge cases. Prompts should be written in second person and kept under 10,000 characters. It describes two creation methods. The first is AI-assisted generation, using a prompt pattern extracted from Claude Code that returns JSON with identifier, whenToUse and systemPrompt. The second is manual creation, saving the file as agents/agent-name.md. Validation rules set lengths for descriptions (10-5,000 characters, best 200-1,000) and system prompts (20-10,000 characters, best 500-3,000). The skill also explains how agents are organized. All .md files in a plugin's agents/ directory are auto-discovered, and agents are namespaced automatically. It covers testing both triggering and system prompt behavior. It points to reference files on system prompt design, triggering examples and the exact agent-creation prompt from Claude Code. It also lists example files and two utility scripts: validate-agent.sh and test-agent-trigger.sh.

Who it's for

• Claude Code plugin developers who want to add autonomous agents to their plugins
• Users who need guidance on agent frontmatter, triggering descriptions, tools or colors
• Developers designing system prompts for subagents
• Anyone validating or testing agent triggering behavior

Requirements

Examples

---
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]

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..."
}

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

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