提示词模板
Agent Skills 完全指南:如何创建高质量的 AI 技能
Agent Skills 是由 Anthropic 维护的开放格式,用于让 AI 获得特定领域的能力和专业知识。本文档提供了创建高质量 Skill 的完整模板和书写要点。
GitHub 地址: https://github.com/anthropics/skills
官方文档: https://agentskills.io
目录
什么是 Agent Skills
Agent Skills 是一种简单、开放的格式,通过包含指令、脚本和资源的文件夹,让 AI 能够在特定任务中表现出色。
核心特点
- ✅ 简单易用:只需创建一个
SKILL.md文件 - ✅ 可重用:编写一次,到处使用
- ✅ 可扩展:支持添加脚本、模板和参考文档
- ✅ 开放标准:基于开放的 Agent Skills 规范
适用场景
- 专业化任务(代码审查、文档处理、数据分析)
- 领域知识(法律、医疗、金融)
- 工作流程自动化(CI/CD、测试、部署)
- 企业定制(品牌规范、内部流程)
Skill 文件结构
一个标准的 Skill 文件由两部分组成:
---
name: skill-name
description: [核心描述]
license: Apache 2.0
---
# 技能名称
[主体内容]
必需元素
- YAML Frontmatter:包含元数据(name、description)
- Markdown 内容:具体的指令和指南
可选元素
- 辅助脚本和工具
- 模板文件
- 参考文档
- 示例代码
第一部分:YAML Frontmatter
YAML Frontmatter 是 Skill 的元数据部分,决定了 AI 何时加载和使用该 Skill。
1. name(必需)
name: skill-name
命名规则
- ✅ 使用小写字母
- ✅ 用连字符
-分隔单词 - ✅ 简洁明了,一眼看出功能
- ✅ 作为唯一标识符
示例对比
| 示例 | 评价 | 原因 |
|---|---|---|
name: pdf-processor |
✅ 优秀 | 小写、连字符、清晰 |
name: code-review-skill |
✅ 优秀 | 小写、连字符、清晰 |
name: PDFTool |
❌ 避免 | 大写字母 |
name: skill for pdf |
❌ 避免 | 包含空格 |
name: my-skill |
❌ 避免 | 过于模糊 |
2. description(最关键)
description 是整个 Skill 最重要的字段,它决定了 AI 何时加载和使用该 Skill。
Description 的黄金法则
一个优秀的 description 必须包含 5 个要素,让 AI 准确理解何时使用该 Skill。
✅ 5 个必备要素
要素 1:核心功能(做什么)
说明该 Skill 能够完成的具体任务和功能。
示例:
处理 PDF 文件的读取、创建、合并、拆分等操作
要素 2:使用场景(何时用)
描述在什么情况下应该使用该 Skill。
示例:
当用户需要处理 PDF 文档、提取内容或转换格式时
要素 3:触发关键词
列出用户可能提到的关键词或短语。
示例:
.pdf 文件、"PDF"、"合并文档"、"拆分页面"、"提取文本"
要素 4:具体能力列表
详细列出 Skill 包含的主要功能。
示例:
包括读取/提取文本/表格、合并/拆分 PDF、旋转页面、添加水印、创建新 PDF、填写表单、加密/解密、提取图片和 OCR
要素 5:否定边界(不做什么)
明确说明该 Skill 不适用于什么场景。
示例:
不用于一般文本处理、Word 文档(.docx)或图片编辑
📝 Description 书写模板
使用以下模板确保 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、find bugs、optimize code
- ✅ 否定边界:不用于编程问题解答、代码生成
❌ 差的 Description 示例
| 错误示例 | 问题描述 |
|---|---|
description: "PDF 工具" |
太模糊,不知道何时用,不知道能做什么 |
description: "帮助用户处理各种文档" |
边界不清晰,和 Word、Excel 混淆 |
description: "代码助手" |
范围太广,不知道具体能力 |
description: "这个 skill 用于创建算法艺术" |
缺少触发关键词和使用场景 |
3. license(可选但推荐)
license: Apache 2.0
常见许可证类型
| 许可证 | 适用场景 | 说明 |
|---|---|---|
Apache 2.0 |
开源 Skill | 推荐,宽松的商业友好的开源许可证 |
MIT |
开源 Skill | 最宽松的开源许可证 |
Proprietary |
私有 Skill | 专有,不公开源码 |
Complete terms in LICENSE.txt |
复杂许可 | 引用完整的许可证文件 |
第二部分:Markdown 主体内容
Markdown 主体是 Skill 的核心指令部分,包含详细的操作指南和规则。
完整结构
# 技能名称
## 1. 身份与定位
[你是谁,你的使命]
## 2. 核心能力
[你能做什么]
## 3. 关键规则
[必须遵守和禁止事项]
## 4. 工作流程
[分步骤的操作指南]
## 5. 使用示例
[实际应用案例]
## 6. 注意事项
[常见问题和陷阱]
## 7. 参考资源
[进一步学习的链接]
部分 1:身份与定位
目的:让 AI 理解该 Skill 的角色定位
书写要点
- 明确角色身份
- 说明专注领域
- 定义核心使命
示例
# 代码审查专家
你是代码审查专家,专注于提供高质量的代码审查、质量分析、bug发现、性能优化建议和安全检查。
你的目标是帮助开发者提升代码质量、可维护性和安全性。
部分 2:核心能力
目的:清晰列出 Skill 包含的所有功能
书写要点
- 按功能分类组织
- 每个功能具体可执行
- 使用动词开头
示例
## 核心能力
### 代码质量分析
- 检查代码的可读性、可维护性和可扩展性
- 识别代码异味(Code Smell)和反模式
- 评估代码复杂度和架构设计
- 提供代码重构建议
### Bug 发现与预防
- 识别潜在的运行时错误和边界情况
- 发现空指针引用、数组越界、资源泄漏等问题
- 检查并发和线程安全问题
- 验证错误处理的完整性
### 性能优化
- 分析时间复杂度和空间复杂度
- 识别性能瓶颈和低效算法
- 提供优化建议和替代方案
- 考虑内存使用和资源管理
### 安全漏洞检查
- 检查常见安全漏洞(SQL注入、XSS、CSRF等)
- 验证输入验证和输出编码
- 评估认证和授权机制
- 检查敏感数据处理
### 代码规范遵循
- 检查是否符合项目代码规范
- 验证命名约定和注释质量
- 评估测试覆盖率和测试质量
- 确保遵循语言最佳实践
部分 3:关键规则(最重要)
目的:明确 AI 必须遵守的规则和禁止事项
这是决定 AI 行为边界的关键部分。
书写要点
- 使用明确的"必须"和"禁止"语言
- 规则具体可执行
- 提供清晰的判断标准
示例
## 关键规则
### 审查原则
- **建设性反馈**:始终提供具体、可执行的改进建议
- **平衡观点**:既指出问题,也认可优点
- **分级严重性**:按严重程度分类问题(严重/重要/建议)
- **上下文感知**:考虑代码的实际使用场景和约束
### 必须检查项
- ✅ 错误处理是否完整
- ✅ 边界条件是否考虑
- ✅ 资源是否正确释放
- ✅ 并发安全性是否保证
- ✅ 安全漏洞是否存在
- ✅ 性能是否合理
- ✅ 代码可读性是否良好
### 禁止行为
- ❌ 不进行无根据的批评
- ❌ 不建议过度工程化
- ❌ 不提出破坏现有接口的激进重构
- ❌ 不忽略上下文和业务逻辑
部分 4:工作流程
目的:提供清晰、可执行的步骤指南
书写要点
- 按步骤顺序组织
- 每个步骤具体可执行
- 包含检查清单
示例
## 工作流程
### 第一步:整体评估
#### 1. 理解代码目的
- 阅读相关文档和注释
- 理解业务逻辑和功能需求
- 识别关键依赖和接口
#### 2. 快速扫描
- 检查整体结构和组织
- 识别明显的代码异味
- 评估测试覆盖情况
### 第二步:详细审查
#### 2.1 功能正确性
```bash
# 检查清单
- 业务逻辑是否正确实现
- 边界条件是否处理
- 错误情况是否覆盖
- 数据验证是否充分
2.2 代码质量
# 检查清单
- 函数/方法长度是否合理(建议 < 50 行)
- 圈复杂度是否可控(建议 < 10)
- 命名是否清晰有意义
- 注释是否准确且必要
- 重复代码是否可以抽取
第三步:问题分类
严重级别定义
🔴 严重
- 安全漏洞
- 数据损坏风险
- 资源泄漏
- 死锁风险
🟡 重要
- 潜在错误
- 性能问题
- 代码异味
- 测试缺失
🟢 建议
- 代码风格
- 可读性改进
- 最佳实践
- 微小优化
第四步:生成审查报告
[具体的报告模板]
---
### 部分 5:使用示例
**目的**:通过实际案例展示如何使用该 Skill
#### 书写要点
- 提供多个场景
- 展示完整的处理流程
- 包含用户请求和 AI 响应
#### 示例
```markdown
## 使用示例
### 示例 1:Python 代码质量审查
**用户请求**:
请帮我审查这段 Python 代码,检查是否有问题:
def calculate_average(numbers):
total = 0
for num in numbers:
total += num
return total / len(numbers)
**处理流程**:
1. **分析代码目的**:计算数字列表的平均值
2. **功能正确性检查**:
- 边界条件:空列表会引发 ZeroDivisionError
- 输入验证:未检查 numbers 是否为空
3. **代码质量检查**:
- 函数长度:合理
- 命名:清晰有意义
- 复杂度:低,易于理解
4. **安全检查**:无明显安全问题
**输出结果**:
代码审查报告
总体评价
代码功能正确但缺少边界条件处理。整体结构清晰,命名规范。
问题清单
🟡 重要问题
-
空列表未处理
-
位置: 函数最后一行
-
描述: 当
numbers为空列表时,len(numbers)返回 0,引发ZeroDivisionError -
影响: 程序崩溃
-
建议: 添加空列表检查
-
示例:
# 修改前 return total / len(numbers) # 修改后 if not numbers: return 0 return total / len(numbers)
-
优点
✅ 函数命名清晰
✅ 逻辑简洁明了
✅ 易于理解
总体评分
- 正确性: 7/10
- 可读性: 9/10
- 可维护性: 8/10
- 性能: 8/10
- 安全性: 10/10
下一步建议
优先处理空列表问题
部分 6:注意事项和常见误区
目的:帮助避免常见错误
书写要点
- 对比正确和错误做法
- 使用清晰的警告标识
- 提供具体示例
示例
## 注意事项
### 常见误区
❌ **错误做法**
```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]
改进点:
- 添加类型注解
- 添加文档字符串
- 使用列表推导式简化代码
关键警告
⚠️ 重要提示
- 始终验证用户输入
- 不要假设数据格式
- 考虑边界条件
- 记录关键操作
最佳实践
✅ 推荐做法
- 使用有意义的变量名
- 保持函数简短(< 50 行)
- 编写清晰的注释
- 编写测试用例
- 遵循语言规范
---
### 部分 7:专项检查清单(可选)
**目的**:针对特定场景的详细检查项
#### 示例
```markdown
## 专项检查清单
### Python 代码检查
```python
# 检查项
□ PEP 8 遵循情况
□ 类型注解使用
□ 异常处理完整性
□ 资源管理(with语句)
□ 导入组织
□ 魔术方法使用
□ 装饰器使用
□ 生成器/迭代器使用
JavaScript/TypeScript 代码检查
// 检查项
□ ESLint 规则遵循
□ 类型安全
□ 异步处理(async/await)
□ 事件循环阻塞
□ 内存泄漏风险
□ 原型链污染
□ this 绑定
□ 模块化
Java 代码检查
// 检查项
□ Java 代码规范
□ 异常处理规范
□ 空指针检查(Optional使用)
□ 资源关闭(try-with-resources)
□ 并发安全性
□ 注解使用
□ 泛型使用
□ 内存管理
---
### 部分 8:评分标准(可选)
**目的**:提供量化的评估标准
#### 示例
```markdown
## 评分标准
| 维度 | 优秀 (8-10) | 良好 (6-7) | 需改进 (< 6) |
|------|-------------|-----------|-------------|
| 正确性 | 无已知bug,边界处理完善 | 有小问题但不影响主要功能 | 存在bug或严重边界问题 |
| 可读性 | 命名清晰,结构简洁 | 整体可读但有改进空间 | 难以理解,命名混乱 |
| 可维护性 | 低耦合高内聚 | 基本合理但有重构空间 | 高耦合难修改 |
| 性能 | 算法高效,无瓶颈 | 性能可接受但有优化空间 | 存在性能问题 |
| 安全性 | 无已知漏洞 | 基本安全但有小风险 | 存在安全漏洞 |
部分 9:参考资源(可选)
目的:提供进一步学习的链接和资源
示例
## 参考资源
### 工具
- **SonarQube**: 综合代码质量分析
- **ESLint/Pylint**: 静态代码分析
- **Coveralls**: 测试覆盖率分析
- **Code Climate**: 代码质量评分
### 文档
- **Anthropic Skills Guide**: https://agentskills.io
- **Clean Code**: Robert C. Martin
- **Refactoring**: Martin Fowler
- **Effective Java**: Joshua Bloch
### 最佳实践
- **Design Patterns**: Gang of Four
- **SOLID Principles**: Robert C. Martin
- **Test-Driven Development**: Kent Beck
高级写作技巧
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]:
"""处理数据列表
Args:
items: 输入数据项列表
Returns:
处理后的结果列表
"""
return [process(item) for item in items]
改进点:
- 添加类型注解
- 添加文档字符串
- 使用列表推导式简化代码
---
### 3. 使用表格对比
通过表格清晰展示对比信息:
```markdown
| 对比项 | 方案 A | 方案 B |
|--------|--------|--------|
| 性能 | 快(O(n)) | 慢(O(n²)) |
| 可读性 | 高 | 中 |
| 复杂度 | 低 | 高 |
| 适用场景 | 大数据量 | 小数据量 |
4. 使用引用块强调
使用引用块突出重要信息:
> **重要**:description 是 Skill 最重要的字段,决定了 AI 何时加载该 Skill。
> **提示**:在 description 中明确列出触发关键词,提高匹配准确度。
> **警告**:避免在关键规则中使用模糊语言,如"应该"、"可以",应使用"必须"、"禁止"。
5. 使用决策树
通过决策树展示复杂的判断逻辑:
## 决策树
任务 → 是否需要处理 PDF?
├─ 是 → 是否需要读取内容?
│ ├─ 是 → 使用 pdfplumber
│ └─ 否 → 使用 pypdf
│
└─ 否 → 检查其他文档类型
├─ Word → 使用 docx 库
├─ Excel → 使用 pandas
└─ 其他 → 提示不支持
完整性检查清单
在创建 Skill 时,使用以下清单确保质量:
Frontmatter 部分
内容部分
质量检查
常见错误与修正
错误 1:Description 太模糊
❌ 错误示例
description: "PDF 工具"
问题:太模糊,不知道何时用,不知道能做什么
✅ 正确示例
description: "当用户需要处理 PDF 文件时使用此技能。包括读取/提取文本/表格、合并/拆分 PDF、旋转页面、添加水印、创建新 PDF、填写表单、加密/解密等功能。"
错误 2:缺少否定边界
❌ 错误示例
description: "处理文档的工具,包括 PDF 和 Word"
问题:边界不清晰,和 Word、Excel 混淆
✅ 正确示例
description: "处理 PDF 文件的工具。不适用于 Word 文档(.docx)或图片文件。"
错误 3:规则不明确
❌ 错误示例
## 规则
- 应该注意安全
- 可以优化性能
问题:使用模糊语言,不具体可执行
✅ 正确示例
## 关键规则
### 必须遵守
- ✅ 始终检查 SQL 注入风险
- ✅ 验证所有用户输入
- ✅ 使用参数化查询
### 禁止事项
- ❌ 绝不信任用户输入
- ❌ 不要在客户端做安全验证
错误 4:流程不完整
❌ 错误示例
## 工作流程
分析代码
检查问题
给出建议
问题:流程不详细,缺少具体步骤
✅ 正确示例
## 工作流程
### 第一步:整体评估
1. 理解代码目的
2. 检查整体结构
3. 识别明显问题
### 第二步:详细审查
1. 功能正确性检查
2. 代码质量分析
3. 性能评估
4. 安全漏洞扫描
### 第三步:问题分类
- 严重问题
- 重要问题
- 改进建议
### 第四步:生成报告
[具体报告模板]
实战案例
案例 1:创建一个 Excel 处理 Skill
Frontmatter
---
name: excel-processor
description: "当用户需要处理 Excel 文件时使用此技能。包括读取/写入数据、数据清洗、数据转换、数据合并、数据透视表生成、图表创建、公式计算、格式设置等功能。如果用户提到 .xlsx、.xls 文件、'Excel'、'电子表格'、'数据表'等关键词,或请求处理表格数据,使用此技能。不用于 CSV 文件处理(使用 csv-skill)或数据库操作。"
license: Apache 2.0
---
主体内容(节选)
# Excel 处理专家
你是 Excel 处理专家,专注于提供高效的 Excel 文件操作和数据分析能力。
你的目标是帮助用户快速处理、分析和可视化 Excel 数据。
## 核心能力
### 数据读取
- 读取 .xlsx、.xls 文件
- 处理多工作表
- 解析单元格格式和公式
- 提取图表和图像
### 数据写入
- 创建新的 Excel 文件
- 写入数据到指定单元格
- 批量写入数据
- 设置单元格格式
### 数据操作
- 数据清洗和转换
- 数据排序和筛选
- 数据合并和拆分
- 数据透视表生成
## 关键规则
### 必须遵守
- ✅ 使用 openpyxl 或 pandas 处理 Excel
- ✅ 保存前验证数据完整性
- ✅ 处理大文件时使用 chunk 分块读取
### 禁止事项
- ❌ 不要尝试处理密码保护的文件
- ❌ 不支持 .xlsb 格式
## 工作流程
### 第一步:文件读取
1. 检查文件格式(.xlsx 或 .xls)
2. 读取文件内容
3. 解析工作表结构
### 第二步:数据处理
1. 执行请求的操作
2. 验证处理结果
3. 处理异常情况
### 第三步:文件保存
1. 验证输出路径
2. 保存文件
3. 确认保存成功
案例 2:创建一个 API 测试 Skill
Frontmatter
---
name: api-tester
description: "当用户需要进行 API 测试和自动化时使用此技能。包括发送 HTTP 请求、处理响应、验证返回数据、性能测试、压力测试、生成测试报告等功能。如果用户提到 'API'、'接口测试'、'HTTP 请求'、'postman'、'curl'、'RESTful'、'GraphQL'等关键词,或请求测试接口,使用此技能。不用于 UI 自动化测试(使用 webapp-testing)。"
license: Apache 2.0
---
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
[场景描述和完整流程]
## 注意事项
### 常见误区
❌ 错误做法
✅ 正确做法
### 关键警告
⚠️ 重要提示
## 参考资源
[工具、文档、最佳实践链接]
总结
创建高质量的 Agent Skills 的关键要点:
- Description 是最重要的字段
- 必须包含 5 个要素
- 明确边界和触发条件
- 避免模糊描述
- 关键规则决定了 AI 的行为
- 使用"必须"和"禁止"
- 规则具体可执行
- 避免模糊语言
- 工作流程必须具体可执行
- 分步骤组织
- 每个步骤清晰
- 包含检查清单
- 提供充分的使用示例
- 多个场景
- 完整流程
- 对比展示
- 注意格式和可读性
- 使用图标和表格
- 层次清晰
- 语言简洁准确
相关资源
- Agent Skills 官方仓库: https://github.com/anthropics/skills
- Agent Skills 规范: https://agentskills.io/specification
- Anthropic 官方文档: https://docs.anthropic.com
- Claude Skills 指南: https://support.claude.com/en/articles/12512198-creating-custom-skills
最后提醒:优秀的 Skill 不仅要有清晰的 description,还要有具体可执行的规则、完整的流程和丰富的示例。始终从使用者的角度思考,提供最有价值的指导。

浙公网安备 33010602011771号