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.
Instalar com Codex ou Claude Copie este prompt, cole no Codex, Claude ou outro assistente e deixe que ele revise a página da skill e instale para você.
Um comando direto ignora o prompt de revisão. Verifique a origem antes de executá-lo.
Instruções da origem · Visualização somente leitura
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
---
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.]
- [Same.]
[Responsibility 1]
[Responsibility 2]
[Step-by-step workflow]
[What to return]
**[Scenario name].**
**Your Core Responsibilities:**
1.
2.
**Analysis Process:**
**Output Format:**
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:
Triggering conditions ("Use this agent when...")
A short prose summary of the typical trigger scenarios
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
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
- 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.
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 [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
