npx skills add ...
npx skills add anthropics/claude-code --skill agent-development
npx skills add anthropics/claude-code --skill agent-development
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.
The same skill content is published under more than one repo. The install counts are split across them; any of these commands works.
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:
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-reviewertest-generatorapi-docs-writersecurity-analyzerBad examples:
helper (too generic)-agent- (starts/ends with hyphen)my_agent (underscores not allowed)ag (too short, < 3 chars)Defines when Claude should trigger this agent. This is the most critical field.
Must include:
<example> blocks showing usage<commentary> explaining why agent triggersFormat:
Best practices:
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.
Visual identifier for agent in UI.
Options: blue, cyan, green, yellow, magenta, red
Guidelines:
Restrict agent to specific tools.
Format: Array of tool names
Default: If omitted, agent has access to all tools
Best practice: Limit tools to minimum needed (principle of least privilege)
Common tool sets:
["Read", "Grep", "Glob"]["Read", "Write", "Grep"]["Read", "Bash", "Grep"]["*"]The markdown body becomes the agent's system prompt. Write in second person, addressing the agent directly.
Standard template:
✅ DO:
❌ DON'T:
Use this prompt pattern (extracted from Claude Code):
Then convert to agent file format with frontmatter.
See examples/agent-creation-prompt.md for complete template.
inherit)agents/agent-name.mdRules:
Length: 10-5,000 characters Must include: Triggering conditions and examples Best: 200-1,000 characters with 2-4 examples
Length: 20-10,000 characters Best: 500-3,000 characters Structure: Clear responsibilities, process, output format
All .md files in agents/ are auto-discovered.
Agents are namespaced automatically:
agent-nameplugin:subdir:agent-nameCreate test scenarios to verify agent triggers correctly:
Ensure system prompt is complete:
| Field | Required | Format | Example |
|---|---|---|---|
| name | Yes | lowercase-hyphens | code-reviewer |
| description | Yes | Text + examples | Use when... ... |
| model | Yes | inherit/sonnet/opus/haiku | inherit |
| color | Yes | Color name | blue |
| tools | No | Array of tool names | ["Read", "Grep"] |
DO:
inherit for model unless specific needDON'T:
For detailed guidance, consult:
references/system-prompt-design.md - Complete system prompt patternsreferences/triggering-examples.md - Example formats and best practicesreferences/agent-creation-system-prompt.md - The exact prompt from Claude CodeWorking examples in examples/:
agent-creation-prompt.md - AI-assisted agent generation templatecomplete-agent-examples.md - Full agent examples for different use casesDevelopment tools in scripts/:
validate-agent.sh - Validate agent file structuretest-agent-trigger.sh - Test if agent triggers correctlyTo create an agent for a plugin:
agents/agent-name.md filescripts/validate-agent.shFocus on clear triggering conditions and comprehensive system prompts for autonomous operation.
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...]tools: ["Read", "Write", "Grep", "Bash"]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]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..."
}✅ Valid: code-reviewer, test-gen, api-analyzer-v2
❌ Invalid: ag (too short), -start (starts with hyphen), my_agent (underscore)plugin-name/
└── agents/
├── analyzer.md
├── reviewer.md
└── generator.md---
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]