first commit
This commit is contained in:
434
文档润色流和知识库构建流/claude-scholar/skills/agent-identifier/SKILL.md
Normal file
434
文档润色流和知识库构建流/claude-scholar/skills/agent-identifier/SKILL.md
Normal file
@@ -0,0 +1,434 @@
|
||||
---
|
||||
name: agent-identifier
|
||||
description: Use when creating or configuring Claude Code agents and their frontmatter.
|
||||
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
|
||||
|
||||
## When to Use
|
||||
|
||||
Use this skill when the user asks to:
|
||||
- Create an agent
|
||||
- Add an agent
|
||||
- Write a subagent
|
||||
- Define agent frontmatter
|
||||
- Decide when to use description examples
|
||||
- Configure agent tools, colors, or model behavior
|
||||
- Design autonomous agent structure, triggering conditions, or system prompts
|
||||
|
||||
## When Not to Use
|
||||
|
||||
Do not use this skill for:
|
||||
- Slash command design
|
||||
- Hook configuration
|
||||
- MCP server setup
|
||||
- General plugin layout questions that belong to `plugin-structure`
|
||||
|
||||
## Agent File Structure
|
||||
|
||||
### Complete Format
|
||||
|
||||
```markdown
|
||||
---
|
||||
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:** 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
|
||||
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
|
||||
|
||||
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... 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 `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 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 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. Include 2-4 triggering examples in description
|
||||
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.
|
||||
Reference in New Issue
Block a user