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.
- License 许可
- MIT
- 最近更新
- 2026-08-19
- Stars
- ★ 2
- Forks
- 0
01 前言 Front Matter
- 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.
02 资源文件 6
- 参考文档examples/agent-creation-prompt.md9.2 KB
- 参考文档examples/complete-agent-examples.md13.8 KB
- 参考文档references/agent-creation-system-prompt.md8.7 KB
- 参考文档references/system-prompt-design.md9.8 KB
- 参考文档references/triggering-examples.md11.3 KB
- 脚本scripts/validate-agent.sh5.7 KB
03 SKILL.md 正文
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-reviewertest-generatorapi-docs-writersecurity-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
inheritfor 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 patternsreferences/triggering-examples.md- Example formats and best practicesreferences/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 templatecomplete-agent-examples.md- Full agent examples for different use cases
Utility Scripts
Development tools in scripts/:
validate-agent.sh- Validate agent file structuretest-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.mdfile - 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.
04 同仓库更多 Skills
youtube-transcript
Extract transcripts from YouTube videos. Use when the user asks for a transcript, subtitles, or captions of a YouTube video and provides a YouTube URL (youtube.com/watch?v=, youtu.be/, or similar). Supports output with or without timestamps.
youtube-thumbnail-design
YouTube thumbnail design with specific dimensions, contrast rules, and mobile preview optimization. Covers safe zones, text placement, face expression psychology, and A/B testing. Use for: YouTube thumbnails, video cover images, click-through optimization. Triggers: youtube thumbnail, thumbnail design, video thumbnail, click through rate, ctr optimization, youtube cover, video cover image, thumbnail maker, thumbnail tips, youtube design, video preview image
youtube-short-maker
Make YouTube Shorts that hold attention with Pexo — vertical 9:16, fast-paced, hook in the first 3 seconds. Describe your topic and Pexo writes the script, generates the shots, picks the models, and assembles a finished Short with music and captions. Use for YouTube Shorts: "youtube short", "make a youtube short", "shorts video", "short-form video". NOT for long-form or landscape video.
xcode-project-setup
Safely modifies Xcode projects (.pbxproj) to add Swift Packages and link files. Use this skill whenever an iOS project needs dependencies installed (e.g. Firebase, Alamofire).
x402
Set up Browser Use Cloud payments with x402 — pay per request from a crypto wallet (USDC on Base mainnet), no signup or API key. Two setups it works out up front — "just use it" (set up a wallet so you or Claude Code can run cloud browser tasks paid from the wallet — Claude writes and runs throwaway scripts, nothing touches your codebase) or "build it in" (install the SDK and write the key + code into your project). Walks through wallet setup, funding, .env, and a ~$1 test run. Use when the user asks about x402, pay-per-use, USDC payments, or wants Browser Use Cloud without an API key. For the free-tier signup (reverse-CAPTCHA → API key), use `browser-use cloud signup` or the `cloud` skill instead.
x-twitter-scraper
Build GitHub Copilot workflows with Xquik X API SDKs, REST endpoints, hosted Apify Actor runs, MCP tools, TweetClaw OpenClaw plugin installs, signed webhooks, tweet search, user lookup, follower exports, media actions, and agent automation.