name: creating-claude-agents description: 使用于创建或改进 Claude Code 智能体。提供关于智能体文件结构、前言、角色定义、工具访问、模型选择和模式验证的专家指导。

创建 Claude Code 智能体 - 专家技能

使用此技能来创建或改进 Claude Code 智能体。提供全面的指导，包括智能体结构、模式验证和构建长期运行的 AI 助手的最佳实践。

何时使用此技能

激活此技能时：

用户要求创建一个新的 Claude Code 智能体
用户想要改进现有的智能体
用户需要帮助智能体前言或结构
用户正在解决智能体验证问题
用户想要了解智能体格式要求
用户询问智能体与技能与斜杠命令的区别

快速参考

智能体文件结构

---
name: agent-name
description: 何时何因使用此智能体
allowed-tools: 阅读，写入，Bash
model: sonnet
agentType: agent
---

# 🔍 智能体显示名称

你是[角色定义 - 描述智能体的角色和专业知识]。

## 指令

[关于智能体做什么的清晰、可操作的指导]

## 流程

[智能体遵循的逐步工作流程]

## 示例

[代码样本和用例展示智能体的能力]

文件位置

所需路径：

.claude/agents/*.md

智能体必须放置在 .claude/agents/ 目录中作为 markdown 文件。

前言要求

必填字段

字段	类型	描述	示例
`name`	string	智能体标识符（小写字母，仅连字符）	`code-reviewer`
`description`	string	功能和用例的简要概述	`审查代码以寻找最佳实践和潜在问题`

可选字段

字段	类型	描述	值
`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个字符
应清楚解释何时使用智能体
以行动词开头：“审查…”, “分析…”, “帮助…”

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

模型值：

sonnet - 均衡的，适合大多数智能体（默认）
opus - 复杂推理，架构决策
haiku - 快速，简单任务
inherit - 使用父对话的模型

内容格式要求

H1 标题（必填）

内容的第一行必须是作为智能体显示标题的 H1 标题：

# 🔍 代码审查员

最佳实践：

包含一个表情图标以便于视觉区分
使用标题大小写
保持简洁（2-5个词）
使其描述性强且易于记忆

角色定义（智能体必需）

在 H1 之后立即使用 “你是…” 格式定义智能体的角色：

你是软件工程原理和安全最佳实践的专家代码审查员。

指南：

以 “你是…” 开始
清晰定义角色和专业知识
为智能体的能力设定期望
建立智能体的方法和语调

内容结构

# 🔍 智能体名称

你是[角色定义]。

## 指令

[智能体做什么以及它如何处理任务]

## 流程

1. [步骤 1]
2. [步骤 2]
3. [步骤 3]

## 示例

[显示好/坏模式的代码样本]

## 指南

- [最佳实践 1]
- [最佳实践 2]

模式验证

智能体必须符合位于： https://github.com/pr-pm/prpm/blob/main/packages/converters/schemas/claude-agent.schema.json 的 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’	前言缺少名称字段	添加 `name: agent-name`
缺少必填字段 ‘description’	前言缺少描述	添加 `description: ...`
无效的名称模式	名称包含大写或特殊字符	仅使用小写和连字符
名称过长	名称超过64个字符	缩短名称
无效的模型值	模型不在枚举中	使用：`sonnet`, `opus`, `haiku`, 或 `inherit`
缺少 H1 标题	内容没有以 # 开始	添加 `# 智能体名称` 作为第一行

工具配置

继承所有工具

省略 allowed-tools 字段以从父对话中继承所有工具：

---
name: full-access-agent
description: 智能体需要访问所有内容
# 没有 allowed-tools 字段 = 继承所有
---

仅特定工具

仅授予最小必要权限：

---
name: read-only-reviewer
description: 审查代码而不做更改
allowed-tools: Read, Grep, Bash
---

Bash 工具限制

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

---
name: git-helper
description: 仅限 Git 操作
allowed-tools: Bash(git *), Read
---

语法：

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

模型选择指南

Sonnet（大多数智能体）

用途：

代码审查
调试
数据分析
一般问题解决

model: sonnet

Opus（复杂推理）

用途：

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

model: opus

Haiku（速度重要）

用途：

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

model: haiku

Inherit（上下文依赖）

用途：

智能体应与用户模型选择匹配
成本敏感性

model: inherit

常见错误

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

最佳实践

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

描述决定了 Claude 自动调用您的智能体的时间。

✅ 好的：

description: 审查代码变更，寻找质量、安全和可维护性问题

❌ 差的：

description: 一个有用的智能体  # 太模糊

2. 定义强大的角色

在 H1 之后立即建立专业知识和方法：

# 🔍 代码审查员

你是 TypeScript 和 React 方面的专家代码审查员，拥有 10 年以上的安全开发经验。你系统地进行代码审查，检查安全漏洞、性能问题和可维护性问题。

3. 提供分步流程

明确指导智能体的工作流程：

## 审查流程

1. **阅读变更**
   - 获取最近的 git diff 或指定文件
   - 理解上下文和目的

2. **系统分析**
   - 检查每个类别（质量、安全、性能）
   - 提供具体的文件：行引用
   - 解释为什么是个问题

3. **提供可操作的反馈**
   - 按严重程度分类
   - 包括修复建议
   - 突出积极的模式

4. 包括示例

展示好和坏的模式：

## 示例

审查错误处理时：

❌ **坏 - 默默失败：**
\`\`\`typescript
try {
  await fetchData();
} catch (error) {
  console.log(error);
}
\`\`\`

✅ **好 - 适当的错误处理：**
\`\`\`typescript
try {
  await fetchData();
} catch (error) {
  logger.error('Failed to fetch data', error);
  throw new AppError('Data fetch failed', { cause: error });
}
\`\`\`

5. 在 H1 中使用图标以便于视觉区分

选择代表智能体目的的表情图标：

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

6. 保持单一责任

每个智能体应该在一个特定任务上表现出色：

✅ 好的：

code-reviewer - 审查代码以寻找质量和安全问题
debugger - 根本原因分析和最小修复

❌ 差的：

code-helper - 审查、调试、测试、重构、文档（太宽泛）

7. 授予最小工具访问权限

遵循最小权限原则：

# 只读分析智能体
allowed-tools: Read, Grep

# 代码修改智能体
allowed-tools: Read, Edit, Bash(git *)

# 全功能开发智能体
allowed-tools: Read, Write, Edit, Bash, Grep, Glob

8. 包括 agentType 以进行往返转换

在前言中始终包括 agentType: agent 以在格式转换期间保留类型信息：

---
name: code-reviewer
description: 审查代码以寻找最佳实践
agentType: agent
---

示例智能体模板

最小智能体

---
name: simple-reviewer
description: 快速代码审查常见问题
allowed-tools: Read, Grep
model: haiku
agentType: agent
---

# 🔍 简单代码审查员

你是专注于快速捕捉常见错误的代码审查员。

## 指令

审查代码：
- 语法错误
- 常见反模式
- 缺少错误处理
- 控制台.log语句

提供简洁的反馈，带有文件：行引用。

全面智能体

---
name: security-auditor
description: 深入安全漏洞分析代码变更
allowed-tools: Read, Grep, WebSearch, Bash(git *)
model: opus
agentType: agent
---

# 🔒 安全审计员

你是专注于应用安全的安全专家，专长于 OWASP Top 10、安全编码实践和威胁建模。你对代码变更进行全面的安全分析。

## 审查流程

1. **收集上下文**
   - 阅读变更的文件
   - 审查 git 历史记录以获取上下文
   - 识别数据流和信任边界

2. **安全分析**
   - 输入验证和清理
   - 认证和授权
   - SQL 注入风险
   - XSS 漏洞
   - CSRF 保护
   - 机密暴露
   - 加密使用
   - 依赖漏洞

3. **威胁评估**
   - 严重程度评级（严重/高/中/低）
   - 评估可利用性
   - 确定业务影响
   - 提供补救指导

4. **报告发现**
   使用结构化格式，必要时引用 CVE。

## 输出格式

**安全评分：X/10**

### 严重问题（立即修复）
- [漏洞] (文件：行) - [解释] - [CVE 如适用] - [修复]

### 高优先级
- [问题] (文件：行) - [解释] - [修复]

### 中等优先级
- [关注点] (文件：行) - [解释] - [建议]

### 最佳实践
- [观察到的安全模式]

**建议：** [批准/请求更改/阻止]

## 示例

### SQL 注入检查

❌ **易受攻击：**
\`\`\`typescript
const query = \`SELECT * FROM users WHERE id = \${userId}\`;
db.query(query);
\`\`\`

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

验证清单

在最终确定智能体之前：

[ ] 名称是小写，仅连字符
[ ] 名称是64个字符或更少
[ ] 描述清楚解释何时使用智能体
[ ] 描述是1024个字符或更少
[ ] 内容以 H1 标题开始（带表情图标）
[ ] 使用 “你是…” 格式定义角色
[ ] 清晰概述流程或指令
[ ] 包括示例（展示好/坏模式）
[ ] 工具访问最小且具体
[ ] 模型选择适合任务复杂性
[ ] 前言中设置 agentType 字段为 “agent”
[ ] 文件保存在 .claude/agents/ 目录
[ ] 智能体已通过实际任务测试
[ ] 考虑边缘情况

模式参考

官方模式 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

智能体与技能与命令

使用智能体时：

✅ 长期助手，具有持久上下文
✅ 复杂的多步骤工作流程
✅ 需要专业知识
✅ 需要工具访问
✅ 重复流程，具有质量标准

使用技能时：

✅ 上下文感知自动激活
✅ 参考文档和模式
✅ 团队标准化
✅ 不需要持久状态

使用斜杠命令时：

✅ 简单、专注的提示
✅ 快速手动调用
✅ 个人生产力快捷方式
✅ 单文件提示

决策树：

需要专门的 AI 助手？
├─ 是 → 需要工具和持久上下文？
│         ├─ 是 → 使用智能体
│         └─ 否 → 快速调用？
│                 ├─ 是 → 使用斜杠命令
│                 └─ 否 → 使用技能
└─ 否 → 只是文档？ → 使用技能

故障排除

智能体未激活

问题： 智能体未在预期时被调用

解决方案：

使描述更具体以匹配用例
验证文件是否在 .claude/agents/*.md
检查前言语法错误
明确请求：“使用 [智能体名称] 智能体”

验证错误

问题： 智能体文件未通过模式验证

解决方案：

检查名称模式（小写，连字符）
验证必填字段（名称，描述）
确保内容以 H1 标题开始
验证模型值是否在枚举中
检查允许的工具拼写和大小写

工具权限被拒绝

问题： 智能体无法访问所需工具

解决方案：

在前言中添加工具到 allowed-tools
使用正确的大写（例如，Read, 不是 read）
对于 Bash 限制，使用模式语法：Bash(git *)
省略 allowed-tools 字段以继承所有工具

智能体性能差

问题： 智能体产生不一致或低质量的结果

解决方案：

加强角色定义
添加更具体的流程步骤
包括好/坏模式的示例
定义明确的输出格式
考虑使用更强大的模型（opus）
将复杂智能体分解为专业智能体

记住： 优秀的智能体是具有清晰角色、分步流程和最小工具访问权限的专家。专注于使每个智能体在一件事上做得非常出色，并具有可衡量的结果。

name: creating-claude-agents description: 使用于创建或改进 Claude Code 智能体。提供关于智能体文件结构、前言、角色定义、工具访问、模型选择和模式验证的专家指导。

创建 Claude Code 智能体 - 专家技能

何时使用此技能

快速参考

智能体文件结构

文件位置

前言要求

必填字段

可选字段

验证规则

内容格式要求

H1 标题（必填）

角色定义（智能体必需）

内容结构

模式验证

模式结构

常见验证错误

工具配置

继承所有工具

仅特定工具

Bash 工具限制

模型选择指南

Sonnet（大多数智能体）

Opus（复杂推理）

Haiku（速度重要）

Inherit（上下文依赖）

常见错误

最佳实践

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

2. 定义强大的角色

3. 提供分步流程

4. 包括示例

5. 在 H1 中使用图标以便于视觉区分

6. 保持单一责任

7. 授予最小工具访问权限

8. 包括 agentType 以进行往返转换

示例智能体模板

最小智能体

全面智能体

验证清单

模式参考

相关文档

智能体与技能与命令

使用智能体时：

使用技能时：

使用斜杠命令时：

故障排除

智能体未激活

验证错误

工具权限被拒绝

智能体性能差