标准 Skill 模板指南

本文档提供了创建高质量 Skill 的完整模板和书写要点。

📋 Skill 文件结构

---
name: skill-name
description: [核心描述]
license: Apache 2.0
---

# 技能标题

[主体内容]

第一部分：YAML Frontmatter（必需）

1. name（必需）

name: skill-name

规则：

✅ 小写字母
✅ 用连字符 - 分隔单词
✅ 简洁明了，一眼看出功能
✅ 作为唯一标识符

示例：

name: pdf-processor           # ✅ 好
name: code-review-skill       # ✅ 好
name: PDFTool               # ❌ 避免（大写）
name: skill for pdf         # ❌ 避免（空格）

2. description（最关键）

description 决定了 AI 何时加载和使用该 skill，是整个 skill 最重要的字段。

✅ 必须包含的 5 个要素

要素 1：核心功能（做什么）

说明该 skill 能够完成的具体任务和功能

要素 2：使用场景（何时用）

描述在什么情况下应该使用该 skill

要素 3：触发关键词

列出用户可能提到的关键词或短语

要素 4：具体能力列表

详细列出 skill 包含的主要功能

要素 5：否定边界（不做什么）

明确说明该 skill 不适用于什么场景

📝 Description 书写模板

description: "当用户需要[核心功能]时使用此技能。包括[具体能力列表]。如果用户提到[关键词1]、[关键词2]、[关键词3]等，或者请求[具体场景]，使用此技能。不适用于[否定边界场景]。"

✅ 优秀的 description 示例

示例 1：PDF 处理

description: "当用户需要处理 PDF 文件时使用此技能。包括读取/提取文本/表格、合并/拆分 PDF、旋转页面、添加水印、创建新 PDF、填写表单、加密/解密、提取图片和 OCR 等功能。如果用户提到 .pdf 文件、'PDF'、'合并文档'、'拆分页面'等关键词，或请求生成 PDF，使用此技能。不用于一般文本处理、Word 文档（.docx）或图片编辑。"

分析：

✅ 核心功能明确：处理 PDF 文件
✅ 使用场景：提到 PDF、操作文档
✅ 具体能力：10+ 功能列表
✅ 触发关键词：.pdf、PDF、合并文档、拆分页面
✅ 否定边界：不用于文本处理、Word、图片

示例 2：代码审查

description: "在用户需要进行代码审查、代码质量分析、发现潜在bug、性能优化建议、安全漏洞检查、代码规范遵循性检查时使用此技能。适用于审查 Python、JavaScript、TypeScript、Java、Go、C++、Rust 等编程语言的代码。当用户提到 'code review'、'代码审查'、'check code quality'、'find bugs'、'optimize code'、'代码质量'等关键词时，应该使用此技能。不用于一般性的编程问题解答或代码生成，专注于对已有代码的深入分析和改进建议。"

分析：

✅ 核心功能：代码审查、质量分析
✅ 使用场景：分析已有代码
✅ 适用范围：7种编程语言
✅ 触发关键词：code review、代码审查、check code quality 等
✅ 否定边界：不用于编程问题解答、代码生成

❌ 差的 description 示例

description: "PDF 工具"

问题：太模糊，不知道何时用，不知道能做什么

description: "帮助用户处理各种文档"

问题：边界不清晰，和 Word、Excel 混淆

description: "代码助手"

问题：范围太广，不知道具体能力

description: "这个 skill 用于创建算法艺术"

问题：缺少触发关键词和使用场景

3. license（可选但推荐）

license: Apache 2.0

常见许可证：

Apache 2.0 - 推荐用于开源 skill
MIT - 宽松开源许可证
Proprietary - 私有许可证
Complete terms in LICENSE.txt - 引用完整许可证文件

第二部分：Markdown 主体内容（必需）

完整结构

# 技能名称

## 1. 身份与定位
[你是谁，你的使命]

## 2. 核心能力
[你能做什么]

## 3. 关键规则
[必须遵守和禁止事项]

## 4. 工作流程
[分步骤的操作指南]

## 5. 使用示例
[实际应用案例]

## 6. 注意事项
[常见问题和陷阱]

## 7. 参考资源
[进一步学习的链接]

部分 1：身份与定位

目的：让 AI 理解该 skill 的角色定位

# 技能名称

你是 [角色]，专注于 [领域]。
你的目标是 [使命]。

示例：

# 代码审查专家

你是代码审查专家，专注于提供高质量的代码审查、质量分析、bug发现、性能优化建议和安全检查。
你的目标是帮助开发者提升代码质量、可维护性和安全性。

部分 2：核心能力

目的：清晰列出 skill 包含的所有功能

## 核心能力

- **功能分类 1**：具体说明
  - 子功能 1
  - 子功能 2

- **功能分类 2**：具体说明
  - 子功能 1
  - 子功能 2

示例：

## 核心能力

### 代码质量分析
- 检查代码的可读性、可维护性和可扩展性
- 识别代码异味（Code Smell）和反模式
- 评估代码复杂度和架构设计
- 提供代码重构建议

### Bug 发现与预防
- 识别潜在的运行时错误和边界情况
- 发现空指针引用、数组越界、资源泄漏等问题
- 检查并发和线程安全问题
- 验证错误处理的完整性

### 性能优化
- 分析时间复杂度和空间复杂度
- 识别性能瓶颈和低效算法
- 提供优化建议和替代方案
- 考虑内存使用和资源管理

### 安全漏洞检查
- 检查常见安全漏洞（SQL注入、XSS、CSRF等）
- 验证输入验证和输出编码
- 评估认证和授权机制
- 检查敏感数据处理

### 代码规范遵循
- 检查是否符合项目代码规范
- 验证命名约定和注释质量
- 评估测试覆盖率和测试质量
- 确保遵循语言最佳实践

部分 3：关键规则（最重要）

目的：明确 AI 必须遵守的规则和禁止事项

## 关键规则

### 必须遵守
- ✅ 规则 1（必须执行）
- ✅ 规则 2（必须执行）

### 禁止事项
- ❌ 禁止 1（绝对不能做）
- ❌ 禁止 2（绝对不能做）

### 审查原则
- 原则 1
- 原则 2

示例：

## 关键规则

### 审查原则
- **建设性反馈**：始终提供具体、可执行的改进建议
- **平衡观点**：既指出问题，也认可优点
- **分级严重性**：按严重程度分类问题（严重/重要/建议）
- **上下文感知**：考虑代码的实际使用场景和约束

### 必须检查项
- ✅ 错误处理是否完整
- ✅ 边界条件是否考虑
- ✅ 资源是否正确释放
- ✅ 并发安全性是否保证
- ✅ 安全漏洞是否存在
- ✅ 性能是否合理
- ✅ 代码可读性是否良好

### 禁止行为
- ❌ 不进行无根据的批评
- ❌ 不建议过度工程化
- ❌ 不提出破坏现有接口的激进重构
- ❌ 不忽略上下文和业务逻辑

部分 4：工作流程

目的：提供清晰、可执行的步骤指南

## 工作流程

### 步骤 1：[步骤名称]

[具体操作说明]

### 步骤 2：[步骤名称]

[具体操作说明]

### 步骤 3：[步骤名称]

[具体操作说明]

示例：

## 工作流程

### 第一步：整体评估

#### 1. 理解代码目的
- 阅读相关文档和注释
- 理解业务逻辑和功能需求
- 识别关键依赖和接口

#### 2. 快速扫描
- 检查整体结构和组织
- 识别明显的代码异味
- 评估测试覆盖情况

### 第二步：详细审查

#### 2.1 功能正确性
```bash
# 检查清单
- 业务逻辑是否正确实现
- 边界条件是否处理
- 错误情况是否覆盖
- 数据验证是否充分

2.2 代码质量

# 检查清单
- 函数/方法长度是否合理（建议 < 50 行）
- 圈复杂度是否可控（建议 < 10）
- 命名是否清晰有意义
- 注释是否准确且必要
- 重复代码是否可以抽取

第三步：问题分类

严重级别定义

🔴 严重

安全漏洞
数据损坏风险
资源泄漏
死锁风险

🟡 重要

潜在错误
性能问题
代码异味
测试缺失

🟢 建议

代码风格
可读性改进
最佳实践
微小优化

第四步：生成审查报告

[具体的报告模板]


---

### 部分 5：使用示例

**目的**：通过实际案例展示如何使用该 skill

```markdown
## 使用示例

### 示例 1：[场景描述]

**用户请求**：

[用户的实际问题]


**处理流程**：
1. 步骤 1
2. 步骤 2
3. 步骤 3

**输出结果**：

[AI 的响应]


### 示例 2：[场景描述]

[同上格式]

部分 6：注意事项和常见误区

目的：帮助避免常见错误

## 注意事项

### 常见误区

❌ **错误做法**

[错误示例]


✅ **正确做法**

[正确示例]


### 关键警告

⚠️ **重要提示**
- 警告 1
- 警告 2

### 最佳实践

✅ **推荐做法**
- 实践 1
- 实践 2

部分 7：专项检查清单（可选）

目的：针对特定场景的详细检查项

## 专项检查清单

### Python 代码检查
```python
# 检查项
□ PEP 8 遵循情况
□ 类型注解使用
□ 异常处理完整性
□ 资源管理（with语句）
□ 导入组织
□ 魔术方法使用
□ 装饰器使用
□ 生成器/迭代器使用

JavaScript/TypeScript 代码检查

// 检查项
□ ESLint 规则遵循
□ 类型安全
□ 异步处理（async/await）
□ 事件循环阻塞
□ 内存泄漏风险
□ 原型链污染
□ this 绑定
□ 模块化


---

### 部分 8：评分标准（可选）

**目的**：提供量化的评估标准

```markdown
## 评分标准

| 维度 | 优秀 (8-10) | 良好 (6-7) | 需改进 (< 6) |
|------|-------------|-----------|-------------|
| 正确性 | 无已知bug，边界处理完善 | 有小问题但不影响主要功能 | 存在bug或严重边界问题 |
| 可读性 | 命名清晰，结构简洁 | 整体可读但有改进空间 | 难以理解，命名混乱 |
| 可维护性 | 低耦合高内聚 | 基本合理但有重构空间 | 高耦合难修改 |
| 性能 | 算法高效，无瓶颈 | 性能可接受但有优化空间 | 存在性能问题 |
| 安全性 | 无已知漏洞 | 基本安全但有小风险 | 存在安全漏洞 |

部分 9：参考资源（可选）

目的：提供进一步学习的链接和资源

## 参考资源

### 工具
- **工具 1**：功能说明
- **工具 2**：功能说明

### 文档
- **文档 1**：链接
- **文档 2**：链接

### 最佳实践
- **书籍 1**：作者
- **文章 1**：链接

🎯 高级写作技巧

1. 使用图标增强可读性

# 标题
## 🎯 子标题
### ✅ 建议
### ❌ 禁止
### ⚠️ 警告
### 💡 技巧
### 📚 资源

2. 使用代码块展示示例

**当前代码**:
```python
def process_data(items):
    result = []
    for item in items:
        result.append(process(item))
    return result

建议改进:

def process_data(items: List[Item]) -> List[Result]:
    """处理数据列表"""
    return [process(item) for item in items]


### 3. 使用表格对比

```markdown
| 对比项 | 方案 A | 方案 B |
|--------|--------|--------|
| 性能 | 快 | 慢 |
| 可读性 | 高 | 中 |
| 复杂度 | 低 | 高 |

4. 使用引用块强调

> **重要**：这是关键信息，必须注意

> **提示**：这是一个有用的建议

5. 使用决策树

## 决策树

任务 → 判断条件?
├─ 是 → 方案A
│ ├─ 成功 → 完成
│ └─ 失败 → 回退
│
└─ 否 → 方案B
├─ 成功 → 完成
└─ 失败 → 方案C

✅ Skill 完整性检查清单

在创建 skill 时，确保：

Frontmatter 部分

name 字段存在且符合规范
description 详细且准确
description 包含 5 个要素
license 明确（如果需要）

内容部分

质量检查

🚫 常见错误

错误 1：Description 太模糊

❌ 错误：

description: "PDF 工具"

✅ 正确：

description: "当用户需要处理 PDF 文件时使用此技能。包括读取/提取文本/表格、合并/拆分 PDF、旋转页面、添加水印、创建新 PDF、填写表单、加密/解密等功能。"

错误 2：缺少否定边界

❌ 错误：

description: "处理文档的工具，包括 PDF 和 Word"

✅ 正确：

description: "处理 PDF 文件的工具。不适用于 Word 文档（.docx）或图片文件。"

错误 3：规则不明确

❌ 错误：

## 规则
- 应该注意安全
- 可以优化性能

✅ 正确：

## 关键规则
### 必须遵守
- ✅ 始终检查 SQL 注入风险
- ✅ 验证所有用户输入
- ✅ 使用参数化查询

### 禁止事项
- ❌ 绝不信任用户输入
- ❌ 不要在客户端做安全验证

错误 4：流程不完整

❌ 错误：

## 工作流程
分析代码
检查问题
给出建议

✅ 正确：

## 工作流程

### 第一步：整体评估
1. 理解代码目的
2. 检查整体结构
3. 识别明显问题

### 第二步：详细审查
1. 功能正确性检查
2. 代码质量分析
3. 性能评估
4. 安全漏洞扫描

### 第三步：问题分类
- 严重问题
- 重要问题
- 改进建议

### 第四步：生成报告
[具体报告模板]

📊 Skill 质量评分

使用以下标准评估你的 skill：

评价维度	优秀 (8-10)	良好 (6-7)	需改进 (< 6)
Description	完整包含5要素，边界清晰	基本完整但有遗漏	模糊不清，边界不明
结构	层次分明，逻辑清晰	结构基本合理	组织混乱
规则	必须/禁止明确，可执行	有规则但不够具体	规则模糊或缺失
流程	步骤详细，可执行	流程基本完整	流程不完整
示例	多个场景，代码完整	有示例但不够	缺少示例
可读性	格式统一，图标恰当	可读但需改进	难以阅读

📝 最终模板总结

---
name: skill-name
description: "当用户需要[核心功能]时使用此技能。包括[具体能力列表]。如果用户提到[关键词1]、[关键词2]等，使用此技能。不适用于[否定边界场景]。"
license: Apache 2.0
---

# 技能名称

你是 [角色]，专注于 [领域]。
你的目标是 [使命]。

## 核心能力

- **能力 1**：具体说明
- **能力 2**：具体说明
- **能力 3**：具体说明

## 关键规则

### 必须遵守
- ✅ 规则 1
- ✅ 规则 2

### 禁止事项
- ❌ 禁止 1
- ❌ 禁止 2

## 工作流程

### 步骤 1：[名称]
[具体操作]

### 步骤 2：[名称]
[具体操作]

## 使用示例

### 示例 1
[场景描述和完整流程]

## 注意事项

### 常见误区
❌ 错误做法
✅ 正确做法

### 关键警告
⚠️ 重要提示

## 参考资源

[工具、文档、最佳实践链接]

记住：description 是最重要的字段，必须包含 5 个要素；关键规则决定了 AI 的行为边界；工作流程必须具体可执行。

提示词模板

标准 Skill 模板指南

📋 Skill 文件结构

第一部分：YAML Frontmatter（必需）

1. name（必需）

2. description（最关键）

✅ 必须包含的 5 个要素

要素 1：核心功能（做什么）

要素 2：使用场景（何时用）

要素 3：触发关键词

要素 4：具体能力列表

要素 5：否定边界（不做什么）

📝 Description 书写模板

✅ 优秀的 description 示例

❌ 差的 description 示例

3. license（可选但推荐）

第二部分：Markdown 主体内容（必需）

完整结构

部分 1：身份与定位

部分 2：核心能力

部分 3：关键规则（最重要）

部分 4：工作流程

2.2 代码质量

第三步：问题分类

严重级别定义

第四步：生成审查报告

部分 6：注意事项和常见误区

部分 7：专项检查清单（可选）

JavaScript/TypeScript 代码检查

部分 9：参考资源（可选）

🎯 高级写作技巧

1. 使用图标增强可读性

2. 使用代码块展示示例

4. 使用引用块强调

5. 使用决策树

✅ Skill 完整性检查清单

Frontmatter 部分

内容部分

质量检查

🚫 常见错误

错误 1：Description 太模糊

错误 2：缺少否定边界

错误 3：规则不明确

错误 4：流程不完整

📊 Skill 质量评分

📝 最终模板总结