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.
---
name: agent-development
description: 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.
version: 0.1.0
---
# 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
```markdown
---
name: agent-identifier
description: Use this agent when [triggering conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.
model: inherit
color: blue
tools: ["Read", "Write", "Grep"]
---
You are [agent role description]...
## When to invoke
[Two to four representative scenarios written as prose, e.g.:]
- **[Scenario name].** [What the situation looks like and what the agent should do.]
- **[Scenario name].** [Same.]
**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** — it is loaded into context whenever the agent is registered, so the harness can decide when to dispatch.
**Must include:**
1. Triggering conditions ("Use this agent when...")
2. A short prose summary of the typical trigger scenarios
3. A pointer to a "When to invoke" section in the agent body for the detailed worked scenarios
**Format:**
```
Use this agent when [conditions]. Typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. See "When to invoke" in the agent body for worked scenarios.
```
**Best practices:**
- Name 2-4 trigger scenarios in the prose summary
- Cover both proactive (assistant invokes itself) and reactive (user requests) triggering
- Cover different phrasings of the same intent
- Be specific about when NOT to use the agent
- Put detailed scenarios in the body under "When to invoke" as a bullet list of prose descriptions
### 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
```yaml
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:**
```markdown
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
- A "When to invoke" section listing 2-4 trigger scenarios as prose bullets
4. Create identifier (lowercase, hyphens, 3-50 chars)
5. Write description with triggering conditions and a short prose summary of trigger scenarios
Return JSON with:
{
"identifier": "agent-name",
"whenToUse": "Use this agent when... Typical triggers include [...]. See \"When to invoke\" in the agent body.",
"systemPrompt": "You are..."
}
```
Then convert to agent file format with frontmatter.
See `examples/agent-creation-prompt.md` for complete template.
### Method 2: Manual Creation
1. Choose agent identifier (3-50 chars, lowercase, hyphens)
2. Write description with examples
3. Select model (usually `inherit`)
4. Choose color for visual identification
5. Define tools (if restricting access)
6. Write system prompt with structure above
7. 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:
1. Write agent with specific triggering examples
2. Use similar phrasing to examples in test
3. Check Claude loads the agent
4. Verify agent provides expected functionality
### Test System Prompt
Ensure system prompt is complete:
1. Give agent typical task
2. Check it follows process steps
3. Verify output format is correct
4. Test edge cases mentioned in prompt
5. Confirm quality standards are met
## Quick Reference
### Minimal Agent
```markdown
---
name: simple-agent
description: Use this agent when [condition]. Typical triggers include [trigger 1] and [trigger 2]. See "When to invoke" in the agent body.
model: inherit
color: blue
---
You are an agent that [does X].
## When to invoke
- **[Scenario A].** [Description.]
- **[Scenario B].** [Description.]
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 | Prose triggers | Use when... Typical triggers include... |
| model | Yes | inherit/sonnet/opus/haiku | inherit |
| color | Yes | Color name | blue |
| tools | No | Array of tool names | ["Read", "Grep"] |
### Best Practices
**DO:**
- ✅ Name 2-4 trigger scenarios in the description (as prose)
- ✅ Put detailed worked scenarios in a "When to invoke" body section, as prose bullets
- ✅ 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 trigger scenarios
- ❌ 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:
1. Define agent purpose and triggering conditions
2. Choose creation method (AI-assisted or manual)
3. Create `agents/agent-name.md` file
4. Write frontmatter with all required fields
5. Write system prompt following best practices
6. Name 2-4 trigger scenarios in description (prose) and detail them in a "When to invoke" body section
7. Validate with `scripts/validate-agent.sh`
8. Test triggering with real scenarios
9. Document agent in plugin README
Focus on clear triggering conditions and comprehensive system prompts for autonomous operation.
don't have the plugin yet? install it then click "run inline in claude" again.
converted unstructured reference guide into implexa skill format by extracting agent name/identifier rules into inputs, agent creation workflow into numbered procedure steps, triggering logic into explicit decision points, frontmatter validation and file structure into output contract, and agent behavior verification into outcome signals
this skill teaches you how to build autonomous agents for claude code plugins. agents are subprocesses that handle complex, multi-step tasks independently without waiting for user input. use this when someone asks to create an agent, add an agent, write a subagent, configure agent frontmatter, define agent triggering conditions, or needs guidance on agent system prompts and best practices. agents differ from commands: commands execute on user request, agents execute autonomously based on triggering conditions you define.
no external connections required. this is a reference and guidance skill. you'll need:
inherit (default, uses parent model), sonnet, opus, or haikublue, cyan, green, yellow, magenta, or red["Read", "Write", "Grep"])choose agent name. use lowercase letters, numbers, hyphens only. must be 3-50 characters, start and end with alphanumeric. bad names: ag (too short), -agent- (starts with hyphen), my_agent (underscores forbidden). good names: code-reviewer, test-generator, api-docs-writer, security-analyzer.
write the triggering description. this is the most critical field. structure it as: "use this agent when [conditions]. typical triggers include [scenario 1 in prose], [scenario 2 in prose], and [scenario 3 in prose]. see 'when to invoke' in the agent body for worked scenarios." keep it 200-1,000 characters. cover both proactive (agent invokes itself) and reactive (user requests) scenarios. name 2-4 different trigger phrasings.
select model. choose one: inherit (recommended, uses parent model), sonnet (balanced), opus (most capable, expensive), or haiku (fast, cheap). default to inherit unless the agent needs specific model capabilities unavailable in the parent.
pick color. choose a distinct color from blue, cyan, green, yellow, magenta, red. use consistently for similar agent types. guidance: blue/cyan for analysis and review, green for success-oriented tasks, yellow for caution and validation, red for critical and security, magenta for creative and generation.
define tools (optional). restrict agent access to minimum necessary tools. format as array: tools: ["Read", "Write", "Grep"]. if omitted, agent accesses all tools. common sets: read-only analysis uses ["Read", "Grep", "Glob"], code generation uses ["Read", "Write", "Grep"], testing uses ["Read", "Bash", "Grep"].
write system prompt in markdown body. address the agent in second person ("you are...", "you will..."). structure with: role description, core responsibilities (numbered list), analysis process (step-by-step workflow), quality standards (bulleted), output format (explicit structure), and edge cases (how to handle specific situations). keep under 10,000 characters, aim for 500-3,000. do not write in first person or use vague language.
add "when to invoke" section in agent body. write 2-4 representative scenarios as prose bullets. format each as "[scenario name]. [what the situation looks like and what the agent should do.]". these are worked examples that correspond to the triggering conditions in frontmatter.
save agent file. create agents/agent-name.md in the plugin directory. auto-discovery loads all .md files in agents/. file will be namespaced as agent-name (single plugin) or plugin:subdir:agent-name (with subdirectories).
validate agent structure. confirm: name passes identifier rules (3-50 chars, alphanumeric start/end, lowercase, hyphens only), description is 10-5,000 characters with triggering conditions, model is one of four allowed values, color is one of six options, system prompt is 20-10,000 characters with clear responsibilities and process, "when to invoke" section has 2-4 prose scenarios.
test agent triggering. write test scenarios using phrasing similar to your triggering examples. verify claude loads the agent in context, agent executes expected workflow, output matches defined format, edge cases behave as specified, quality standards are met.
if agent needs specific model capabilities (e.g., complex reasoning): use opus. if agent is simple and latency matters, use haiku. otherwise use inherit to match parent model.
if agent should run autonomously without explicit user request: include "proactive invocation" scenarios in "when to invoke" section and describe self-triggering conditions in description field.
if agent should run only on user request: describe reactive triggering (e.g., "when user asks to review code", "when user requests security analysis") in description and provide user-initiated scenarios.
if agent needs restricted tool access (security or focus): define tools array with specific tool names. if unrestricted access is needed, omit tools field or use ["*"].
if agent will be used alongside other agents in same plugin: choose distinct, semantically appropriate colors to differentiate roles in UI.
if triggering conditions are complex or multi-faceted: name all 2-4 trigger patterns in description prose, then expand each with detailed worked scenario in "when to invoke" body section.
if system prompt exceeds 3,000 characters: consider splitting into two agents or removing low-priority edge cases.
successful agent creation produces a single markdown file at agents/agent-name.md with:
name (string, 3-50 chars), description (string, 10-5,000 chars with triggering conditions), model (one of: inherit, sonnet, opus, haiku), color (one of: blue, cyan, green, yellow, magenta, red), tools (optional array of strings)you know the agent works when: