create-agent
Comprehensive guide for creating Claude Code agents with proper structure, triggering conditions, system prompts, and validation - combines official Anthropic best practices with proven patterns
NeoLabHQ · 已有 AI 审核记录
安装与使用
运行命令前先阅读来源与依赖说明。复制命令不会自动安装或执行。
npx skills add NeoLabHQ/context-engineering-kit --skill create-agent技能说明
name: create-agent description: Comprehensive guide for creating Claude Code agents with proper structure, triggering conditions, system prompts, and validation - combines official Anthropic best practices with proven patterns
Create Agent Command
Create autonomous Claude Code agents that handle complex, multi-step tasks independently. This command provides comprehensive guidance based on official Anthropic documentation and proven patterns.
User Input
Agent Name: $1
Description: $2
What Are Agents?
Agents are autonomous subprocesses spawned via the Task tool that:
- Handle complex, multi-step tasks independently
- Have their own isolated context window
- Return results to the parent conversation
- Can be specialized for specific domains
| Concept | Agent | Command |
|---|---|---|
| Trigger | Claude decides based on description | User invokes with /name |
| Purpose | Autonomous work | User-initiated actions |
| Context | Isolated subprocess | Shared conversation |
| File format | agents/*.md | commands/*.md |
Agent File Structure
Agents use a unique format combining YAML frontmatter with a markdown system prompt:
---
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 Reference
Required Fields
name (Required)
Format: Lowercase with hyphens only Length: 3-50 characters Rules:
- Must start and end with alphanumeric character
- Only lowercase letters, numbers, and hyphens
- No underscores, spaces, or special characters
| Valid | Invalid | Reason |
|---|---|---|
code-reviewer | helper | Too generic |
test-generator | -agent- | Starts/ends with hyphen |
api-docs-writer | my_agent | Underscores not allowed |
security-analyzer | ag | Too short (<3 chars) |
pr-quality-reviewer | MyAgent | Uppercase not allowed |
description (Required, Critical)
The most important field - Defines when Claude triggers the agent.
Requirements:
- Length: 10-5,000 characters (ideal: 200-1,000 with 2-4 examples)
- MUST start with: "Use this agent when..."
- MUST include:
<example>blocks showing usage patterns - Each example needs: context, user request, assistant response, commentary
Example Block Format:
<example>
Context: [Describe the situation - what led to this interaction]
user: "[Exact user message or request]"
assistant: "[How Claude should respond before triggering]"
<commentary>
[Explanation of why this agent should be triggered in this scenario]
</commentary>
assistant: "[How Claude triggers the agent - 'I'll use the [agent-name] agent...']"
</example>
Best Practices for Descriptions:
- Include 2-4 concrete examples
- Show both proactive and reactive triggering scenarios
- Cover different phrasings of the same intent
- Explain reasoning in commentary
- Be specific about when NOT to use the agent
model (Required)
Values: inherit, sonnet, opus, haiku
Default: inherit (recommended)
| Value | Use Case | Cost |
|---|---|---|
inherit | Use parent conversation model | Default |
haiku | Fast, simple tasks | Lowest |
sonnet | Balanced performance | Medium |
opus | Maximum capability, complex reasoning | Highest |
Recommendation: Use inherit unless you have a specific reason to override.
color (Required)
Purpose: Visual indicator in UI to distinguish agents
Values: blue, cyan, green, yellow, magenta, red
Best Practice: Use different colors for different agents in the same plugin to distinguish them visually.
Optional Fields
tools (Optional)
Purpose: Restrict available tools (principle of least privilege) Format: Array of tool names Default: All tools available
# Common tool restrictions
tools: ["Read", "Grep", "Glob"] # Read-only analysis
tools: ["Read", "Write", "Grep", "Glob"] # Code modification
tools: ["Read", "Bash", "Grep"] # System operations
Security Principle: Only grant tools the agent actually needs.
Triggering Patterns
Pattern 1: Explicit Request
User directly asks for the agent's function.
<example>
Context: User wants code reviewed
user: "Can you review my code changes?"
assistant: "I'll use the code-reviewer agent to analyze the changes."
<commentary>
User explicitly requested code review, trigger the code-reviewer agent.
</commentary>
</example>
Pattern 2: Implicit Need
Agent needed based on context, not explicit request.
<example>
Context: User mentions code is hard to understand
user: "This code is confusing and hard to follow"
assistant: "I can help improve the code clarity."
<commentary>
User indicates complexity issues. Trigger code-simplifier agent to refactor
for better readability.
</commentary>
assistant: "I'll use the code-simplifier agent to suggest improvements."
</example>
Pattern 3: Proactive Trigger
Agent triggers after completing relevant work without explicit request.
<example>
Context: User just implemented database queries
user: "I've added the user search functionality"
assistant: "Great! Let me review it for security."
<commentary>
Database code written. Proactively trigger security-analyzer to check
for SQL injection and other database security issues
阅读完整来源 ↗