代理标识开发_agent-identifier

以下为本文档的中文说明

该技能为Claude Code插件中的代理开发提供全面指导，涵盖代理结构设计、触发条件配置、系统提示词编写等关键方面。主要功能是帮助开发者创建自主化的子代理，使其能够独立处理复杂的多步骤任务。使用场景包括：当用户需要"创建代理"、“添加代理”、"编写子代理"时提供模板和最佳实践；指导如何设置代理的触发条件、工具权限和运行模型；以及如何设计有效的系统提示词来描述代理行为。核心原则包括：代理（Agent）用于自主工作，命令（Command）用于用户发起的操作——两者有明确的职责区分；Markdown文件格式配合YAML前置元数据定义代理结构；通过描述字段中的示例来定义触发条件；系统提示词决定代理的行为模式和边界。该技能还涵盖模型选择、颜色定制和工具配置等内容，帮助开发者构建功能强大、行为可控的自主代理。

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

Must include:

1. Triggering conditions (“Use this agent when…”)
2. Multiple<example>blocks showing usage
3. Context, user request, and assistant response in each example
4. <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:Useinheritunless 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. [S tep 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.

Seeexamples/agent-creation-prompt.mdfor complete template.

Method 2: Manual Creation

1. Choose agent identifier (3-50 chars, lowercase, hyphens)
2. Write description with examples
3. Select model (usuallyinherit)
4. Choose color for visual identification
5. Define tools (if restricting access)
6. Write system prompt with structure above
7. Save asagents/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.mdfiles inagents/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

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

Best Practices

DO:

• ✅ Include 2-4 concrete examples in description
• ✅ Write specific triggering conditions
• ✅ Useinheritfor 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 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 inexamples/:

• agent-creation-prompt.md- AI-assisted agent generation template
• complete-agent-examples.md- Full agent examples for different use cases

Utility Scripts

Development tools inscripts/:

• 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. Createagents/agent-name.mdfile
4. Write frontmatter with all required fields
5. Write system prompt following best practices
6. Include 2-4 triggering examples in description
7. Validate withscripts/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.
3c:[“","","","L3f”,null,{“content”:“$40”,“frontMatter”:{“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”}}]

3d:[“KaTeX parse error: Expected '}', got 'EOF' at end of input: …,"children":[["”,“div”,null,{“className”:“flex items-center justify-between border-b border-border bg-muted/30 px-4 py-2.5”,“children”:[[“KaTeX parse error: Expected '}', got 'EOF' at end of input: …","children":["”,“span”,null,{“className”:“truncate text-xs font-medium text-muted-foreground”,“children”:“同仓库更多 Skills”}]}],[“KaTeX parse error: Expected 'EOF', got '}' at position 88: …ldren":"同仓库"}]]}̲],["”,“div”,null,{“className”:“p-4 sm:p-5”,“children”:[[“","h2",null,"id":"related−skills−heading","className":"text−2xlfont−semiboldtracking−normaltext−foreground","children":"同仓库更多Skills"],["","h2",null,{"id":"related-skills-heading","className":"text-2xl font-semibold tracking-normal text-foreground","children":"同仓库更多 Skills"}],["","h2",null,"id":"related−skills−heading","className":"text−2xlfont−semiboldtracking−normaltext−foreground","children":"同仓库更多Skills"],["”,“div”,null,{“className”:“mt-4 grid gap-3 sm:grid-cols-2”,“children”:[“L41","L41","L41","L42”,“L43","L43","L43","L44”,“L45","L45","L45","L46”]}]]}]]}]

47:I[206516,[“/_next/static/chunks/051aanbhrv4br.js”,“/_next/static/chunks/0mizr60h7ayzt.js”,“/_next/static/chunks/0v9lm1dmbdoo-.js”,“/_next/static/chunks/0rxr1j1j3j-.r.js”,“/_next/static/chunks/02ftybezfvqjd.js”,“/_next/static/chunks/0.v9ksvnnj8ia.js”,“/_next/static/chunks/0bn6id9_{6nx3k.js",“/_next/static/chunks/13ybnhn37c.tc.js”,“/_next/static/chunks/0_fnrdtruz8uf.js”,“/_next/static/chunks/0r6l15utt1mwb.js”,“/_next/static/chunks/0dm9a5into854.js”,"/_next/static/chunks/0}7k6hqoibtcn.js”,“/next/static/chunks/0b4cao.4y…j.js”,“/_next/static/chunks/02i-n28z7kjd0.js”],“default”]