creating-claude-agents

创建 Claude Code Agent - 专家技能

创建或改进 Claude Code Agent 时使用此技能。它提供有关 Agent 结构、架构验证以及构建可长期运行的 AI 助手的最佳实践的全面指导。

何时使用此技能

在以下情况下启用此技能：

• 用户要求创建新的 Claude Code Agent
• 用户想改进现有 Agent
• 用户需要有关 Agent frontmatter 或结构的帮助
• 用户正在排查 Agent 验证问题
• 用户想了解 Agent 格式要求
• 用户询问 Agent、技能与斜杠命令之间的区别

快速参考

Agent 文件结构

---
name: agent-name
description: When and why to use this agent
allowed-tools: Read, Write, Bash
model: sonnet
agentType: agent
---

# 🔍 Agent Display Name

You are [persona definition - describe the agent's role and expertise].

## Instructions

[Clear, actionable guidance on what the agent does]

## Process

[Step-by-step workflow the agent follows]

## Examples

[Code samples and use cases demonstrating the agent's capabilities]

文件位置

必需路径：

.claude/agents/*.md

Agent 必须以 Markdown 文件的形式放在 .claude/agents/ 目录中。

Frontmatter 要求

必填字段

字段	类型	描述	示例
name	string	Agent 标识符（仅限小写字母和连字符）	code-reviewer
description	string	功能和使用场景的简要概述	Reviews code for best practices and potential issues

可选字段

字段	类型	描述	值
allowed-tools	string	可用工具的逗号分隔列表	Read, Write, Bash, WebSearch
model	string	要使用的 Claude 模型	sonnet、opus、haiku、inherit
agentType	string	用于保留格式的显式标记	agent

验证规则

名称字段：

• 模式：^[a-z0-9-]+$（仅限小写字母、数字和连字符）
• 最大长度：64 个字符
• 示例：✅ code-reviewer ❌ Code_Reviewer

描述字段：

• 最大长度：1024 个字符
• 应清楚说明何时使用该 Agent
• 以动作词开头：“Reviews...”、“Analyzes...”、“Helps with...”

允许的工具： 有效工具：Read、Write、Edit、Grep、Glob、Bash、WebSearch、WebFetch、Task、Skill、SlashCommand、TodoWrite、AskUserQuestion

模型值：

• sonnet - 平衡，适用于大多数 Agent（默认值）
• opus - 复杂推理和架构决策
• haiku - 快速处理简单任务
• inherit - 使用父级对话的模型

内容格式要求

H1 标题（必需）

内容的第一行必须是 H1 标题，作为 Agent 的显示标题：

# 🔍 Code Reviewer

最佳实践：

• 添加 emoji 图标以便于视觉区分
• 使用标题式大小写
• 保持简洁（2-5 个词）
• 使其具有描述性且易于记忆

Persona 定义（Agent 必需）

在 H1 标题后立即使用“You are...”格式定义 Agent 的 persona：

You are an expert code reviewer with deep knowledge of software engineering principles and security best practices.

指南：

• 以“You are...”开头
• 清楚定义角色和专长
• 明确 Agent 的能力预期
• 确定 Agent 的方法和语气

内容结构

# 🔍 Agent Name

You are [persona definition].

## Instructions

[What the agent does and how it approaches tasks]

## Process

1. [Step 1]
2. [Step 2]
3. [Step 3]

## Examples

[Code samples showing good/bad patterns]

## Guidelines

- [Best practice 1]
- [Best practice 2]

架构验证

Agent 必须符合以下 JSON 架构： https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-agent.schema.json

架构结构

{
  "frontmatter": {
    "name": "string (required)",
    "description": "string (required)",
    "allowed-tools": "string (optional)",
    "model": "enum (optional)",
    "agentType": "agent (optional)"
  },
  "content": "string (markdown with H1, persona, instructions)"
}

常见验证错误

错误	原因	修复
缺少必填字段 'name'	Frontmatter 缺少 name 字段	添加 name: agent-name
缺少必填字段 'description'	Frontmatter 缺少 description	添加 description: ...
名称格式无效	名称包含大写字母或特殊字符	仅使用小写字母和连字符
名称过长	名称超过 64 个字符	缩短名称
模型值无效	模型不在枚举范围内	使用：sonnet、opus、haiku 或 inherit
缺少 H1 标题	内容未以 # 开头	将 # Agent Name 添加为第一行

工具配置

继承所有工具

省略 allowed-tools 字段，即可继承父级对话中的所有工具：

---
name: full-access-agent
description: Agent needs access to everything
# No allowed-tools field = inherits all
---

仅使用特定工具

授予最低限度的必要权限：

---
name: read-only-reviewer
description: Reviews code without making changes
allowed-tools: Read, Grep, Bash
---

Bash 工具限制

使用命令模式限制 Bash 访问：

---
name: git-helper
description: Git operations only
allowed-tools: Bash(git *), Read
---

语法：

• Bash(git *) - 仅限 git 命令
• Bash(npm test:*) - 仅限 npm 测试脚本
• Bash(git status:*)、Bash(git diff:*) - 多个指定命令

模型选择指南

Sonnet（适用于大多数 Agent）

适用于：

• 代码审查
• 调试
• 数据分析
• 常规问题解决

model: sonnet

Opus（复杂推理）

适用于：

• 架构决策
• 复杂重构
• 深度安全分析
• 新颖问题的解决

model: opus

Haiku（速度优先）

适用于：

• 语法检查
• 简单格式化
• 快速验证
• 低延迟需求

model: haiku

Inherit（取决于上下文）

适用于：

• Agent 应采用与用户相同的模型选择
• 对成本敏感

model: inherit

常见错误

错误	问题	解决方案
名称中使用 _	违反格式限制	使用连字符：code-reviewer，而不是 code_reviewer
名称中使用大写字母	违反格式限制	仅使用小写字母：debugger，而不是 Debugger
缺少角色设定	Agent 缺少角色定义	在 H1 标题后添加“你是……”
没有 H1 标题	内容格式无效	以 # Agent Name 开始内容
描述含糊	Agent 无法正确激活	明确说明何时使用
工具过多	存在安全风险，违反最小权限原则	仅授予必要的工具
没有 agentType 字段	转换时可能丢失类型信息	添加 agentType: agent
Agent 名称过于通用	可能产生冲突或用途不明确	使用具体且有描述性的名称

最佳实践

1. 编写清晰、具体的描述

描述决定了 Claude 何时自动调用你的 Agent。

✅ 良好示例：

description: Reviews code changes for quality, security, and maintainability issues

❌ 较差示例：

description: A helpful agent # Too vague

2. 定义鲜明的角色设定

在 H1 标题后立即确立专业能力和行事方式：

# 🔍 Code Reviewer

You are an expert code reviewer specializing in TypeScript and React, with 10+ years of experience in security-focused development. You approach code review systematically, checking for security vulnerabilities, performance issues, and maintainability concerns.

3. 提供分步流程

明确引导 Agent 的工作流：

## Review Process

1. **Read the changes**
   - Get recent git diff or specified files
   - Understand the context and purpose

2. **Analyze systematically**
   - Check each category (quality, security, performance)
   - Provide specific file:line references
   - Explain why something is an issue

3. **Provide actionable feedback**
   - Categorize by severity
   - Include fix suggestions
   - Highlight positive patterns

4. 添加示例

展示正确和错误的模式：

## Examples

When reviewing error handling:

❌ **Bad - Silent failure:**
\`\`\`typescript
try {
await fetchData();
} catch (error) {
console.log(error);
}
\`\`\`

✅ **Good - Proper error handling:**
\`\`\`typescript
try {
await fetchData();
} catch (error) {
logger.error('Failed to fetch data', error);
throw new AppError('Data fetch failed', { cause: error });
}
\`\`\`

5. 在 H1 标题中使用图标以便区分

选择能体现 Agent 用途的表情符号：

• 🔍 代码审查员
• 🐛 调试器
• 📊 数据科学家
• 🔒 安全审计员
• ⚡ 性能优化器
• 📝 文档编写员
• 🧪 测试生成器

6. 坚持单一职责

每个 Agent 都应专精于一项特定任务：

✅ 良好示例：

• code-reviewer - 检查代码质量和安全性
• debugger - 分析根本原因并进行最小化修复

❌ 不佳示例：

• code-helper - 检查、调试、测试、重构和编写文档（范围过广）

7. 授予最少的工具访问权限

遵循最小权限原则：

# Read-only analysis agent
allowed-tools: Read, Grep

# Code modification agent
allowed-tools: Read, Edit, Bash(git *)

# Full development agent
allowed-tools: Read, Write, Edit, Bash, Grep, Glob

8. 包含 agentType 以支持往返转换

始终在 frontmatter 中包含 agentType: agent，以便在格式转换期间保留类型信息：

---
name: code-reviewer
description: Reviews code for best practices
agentType: agent
---

Agent 模板示例

最简 Agent

---
name: simple-reviewer
description: Quick code review for common issues
allowed-tools: Read, Grep
model: haiku
agentType: agent
---

# 🔍 Simple Code Reviewer

You are a code reviewer focused on catching common mistakes quickly.

## Instructions

Review code for:

- Syntax errors
- Common anti-patterns
- Missing error handling
- Console.log statements

Provide concise feedback with file:line references.

完整 Agent

---
name: security-auditor
description: Deep security vulnerability analysis for code changes
allowed-tools: Read, Grep, WebSearch, Bash(git *)
model: opus
agentType: agent
---

# 🔒 Security Auditor

You are a security expert specializing in application security, with expertise in OWASP Top 10, secure coding practices, and threat modeling. You perform thorough security analysis of code changes.

## Review Process

1. **Gather Context**
   - Read changed files
   - Review git history for context
   - Identify data flows and trust boundaries

2. **Security Analysis**
   - Input validation and sanitization
   - Authentication and authorization
   - SQL injection risks
   - XSS vulnerabilities
   - CSRF protection
   - Secrets exposure
   - Cryptography usage
   - Dependency vulnerabilities

3. **Threat Assessment**
   - Rate severity (Critical/High/Medium/Low)
   - Assess exploitability
   - Determine business impact
   - Provide remediation guidance

4. **Report Findings**
   Use structured format with CVE references where applicable.

## Output Format

**Security Score: X/10**

### Critical Issues (Fix Immediately)

- [Vulnerability] (file:line) - [Explanation] - [CVE if applicable] - [Fix]

### High Priority

- [Issue] (file:line) - [Explanation] - [Fix]

### Medium Priority

- [Concern] (file:line) - [Explanation] - [Recommendation]

### Best Practices

- [Positive security pattern observed]

**Recommendation:** [Approve/Request Changes/Block]

## Examples

### SQL Injection Check

❌ **Vulnerable:**
\`\`\`typescript
const query = \`SELECT \* FROM users WHERE id = \${userId}\`;
db.query(query);
\`\`\`

✅ **Safe:**
\`\`\`typescript
const query = 'SELECT \* FROM users WHERE id = $1';
db.query(query, [userId]);
\`\`\`

验证清单

完成 Agent 前，请确认：

• 名称仅使用小写字母和连字符
• 名称不超过 64 个字符
• 描述清楚说明何时使用该 Agent
• 描述不超过 1024 个字符
• 内容以 H1 标题开头（带有 emoji 图标）
• 使用“You are...”格式定义角色
• 清楚列出流程或说明
• 包含示例（展示良好和不佳的模式）
• 工具访问权限最少且明确
• 模型选择适合任务复杂度
• agentType 字段设为 "agent"
• 文件保存在 .claude/agents/ 目录中
• 已使用真实任务测试 Agent
• 已考虑边缘情况

架构参考

官方架构 URL：

https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-agent.schema.json

本地架构路径：

/Users/khaliqgant/Projects/prpm/app/packages/converters/schemas/claude-agent.schema.json

相关文档

• agent-builder 技能 - 创建高效的子 Agent
• slash-command-builder 技能 - 用于更简单、基于命令的提示词
• creating-skills 技能 - 用于具备上下文感知能力的参考文档
• Claude Code 文档：https://docs.claude.com/claude-code

Agent、技能与命令的区别

适合使用 Agent 的情况：

• ✅ 需要持久上下文的长时间运行助手
• ✅ 复杂的多步骤工作流
• ✅ 需要专业知识
• ✅ 需要工具访问权限
• ✅ 具有质量标准的可重复流程

适合使用技能的情况：

• ✅ 根据上下文自动激活
• ✅ 参考文档和模式
• ✅ 团队标准化
• ✅ 无需持久状态

适合使用斜杠命令的情况：

• ✅ 简单、专注的提示词
• ✅ 快速手动调用
• ✅ 个人效率快捷方式
• ✅ 单文件提示词

决策树：

Need specialized AI assistant?
├─ Yes → Needs tools and persistent context?
│         ├─ Yes → Use Agent
│         └─ No → Quick invocation?
│                 ├─ Yes → Use Slash Command
│                 └─ No → Use Skill
└─ No → Just documentation? → Use Skill

故障排除

Agent 未激活

问题： 未按预期调用 Agent

解决方案：

1. 让描述更具体，以匹配使用场景
2. 确认文件位于 .claude/agents/*.md
3. 检查 frontmatter 是否存在语法错误
4. 明确提出请求：“使用 [agent-name] Agent”

验证错误

问题： Agent 文件未通过架构验证

解决方案：

1. 检查名称格式（仅小写字母和连字符）
2. 确认必需字段（name、description）
3. 确保内容以 H1 标题开头
4. 确认 model 值属于枚举范围
5. 检查 allowed-tools 的拼写和大小写

工具权限被拒绝

问题： Agent 无法访问所需工具

解决方案：

1. 在 frontmatter 的 allowed-tools 中添加工具
2. 使用正确的大小写（例如，使用 Read，而非 read）
3. 对于 Bash 限制，使用模式语法：Bash(git *)
4. 省略 allowed-tools 字段以继承所有工具

Agent 表现不佳

问题： Agent 生成的结果不一致或质量较低

解决方案：

1. 强化角色定义
2. 添加更具体的流程步骤
3. 纳入良好和不佳模式的示例
4. 明确输出格式
5. 考虑使用更强大的模型（opus）
6. 将复杂 Agent 拆分为多个专业 Agent

请记住： 优秀的 Agent 是专业领域的专家，拥有清晰的角色、循序渐进的流程和最少的工具访问权限。让每个 Agent 专注于把一件事做到极致，并取得可衡量的成果。