编写 Skills
编写高质量的 Skill 需要理解 AI 如何解读指令，以及如何设计清晰的工作流程。本章将详细介绍编写 Skill 的核心技巧。
编写流程
编写一个 Skill 通常遵循以下步骤：
- 明确目标：确定 Skill 要解决什么问题
- 设计触发条件：编写精准的 description
- 定义角色：让 AI 理解它扮演的角色
- 编写指令：详细描述工作流程和输出要求
- 测试优化：验证效果并持续改进
第一步：明确目标
在开始编写之前，先回答以下问题：
- 这个 Skill 解决什么具体问题？
- 目标用户是谁？
- 期望的输出是什么？
- 有哪些边界情况需要处理？
示例：代码审查 Skill
假设我们要编写一个代码审查 Skill，目标定义如下：
问题：团队代码审查标准不一致，经常遗漏关键问题
目标用户：开发团队成员
期望输出：结构化的审查报告，包含问题列表和改进建议
边界情况：空文件、超大文件、非代码文件
第二步：设计触发条件
description 字段决定了 Skill 何时被触发，这是最关键的设计决策之一。
触发条件设计原则
原则一：明确功能范围
❌ 太宽泛
description: "帮助处理代码相关的问题"
✅ 明确范围
description: "审查 Python 代码质量，检查命名规范、类型注解、文档字符串。当用户请求代码审查或提交 Python 代码时触发。"
原则二：包含触发关键词
AI 会根据用户输入和 description 的匹配度决定是否触发 Skill。因此，description 中应包含用户可能使用的关键词。
用户可能的说法：
- "帮我审查这段代码"
- "检查一下这个 Python 文件"
- "代码 review"
对应的 description：
description: "审查 Python 代码质量...当用户请求代码审查、代码检查、代码 review 或提交 Python 代码时触发。"
原则三：避免过度触发
❌ 可能过度触发
description: "处理所有 Python 相关问题"
✅ 精准触发
description: "审查 Python 代码质量...当用户明确请求代码审查时触发，不适用于代码编写或调试场景。"
第三步：定义角色
角色定义帮助 AI 理解它应该具备的专业视角和判断标准。
角色定义模板
# [角色名称]
你是一位专业的 [职业身份]，精通 [核心技能]。
## 专业背景
- [相关经验]
- [专业领域]
## 核心原则
- [原则一]
- [原则二]
示例
# Python 代码审查专家
你是一位资深的 Python 开发工程师，拥有 10 年以上的代码审查经验，精通 PEP 8 规范和 Python 最佳实践。
## 专业背景
- 参与过多个大型 Python 项目的代码审查
- 熟悉 Django、FastAPI、Flask 等主流框架
- 对性能优化和代码可维护性有深入理解
## 核心原则
- 代码首先是给人看的，其次才是给机器执行的
- 一致性比个人偏好更重要
- 每条建议都应该有理有据
第四步：编写指令
指令是 Skill 的核心内容，需要详细描述工作流程和输出要求。
指令结构
一个完整的指令通常包含以下部分：
## 工作流程
### 第一步：[步骤名称]
[详细描述]
### 第二步：[步骤名称]
[详细描述]
## 检查清单
- [ ] 检查项一
- [ ] 检查项二
## 输出格式
[输出模板]
## 注意事项
- [注意点一]
- [注意点二]
工作流程示例
## 工作流程
### 第一步：快速扫描
快速浏览代码，识别明显的问题：
- 语法错误
- 导入问题
- 明显的逻辑错误
### 第二步：详细审查
逐项检查以下内容：
#### 代码风格
- 命名是否符合 PEP 8 规范
- 缩进是否一致（4 空格）
- 行长度是否超过 88 字符
#### 类型注解
- 函数参数是否有类型注解
- 返回值是否有类型注解
- 类型注解是否正确
#### 文档
- 模块级 docstring 是否存在
- 函数/方法 docstring 是否存在
- docstring 格式是否规范
### 第三步：生成报告
按照输出格式整理审查结果。
输出格式定义
清晰的输出格式让结果更易读、更专业：
## 输出格式
请按以下格式输出审查结果：
### 📊 审查摘要
- 文件：[文件名]
- 总行数：[行数]
- 问题数量：[数量]
### 🔴 严重问题
[列出可能导致错误的问题]
### 🟡 警告
[列出代码风格问题]
### 🔵 建议优化
[列出优化建议]
### ✅ 改进建议
[针对主要问题给出具体修改方案]
### 📝 总体评价
[简要总结代码质量，给出评分 1-10]
第五步：测试优化
编写完成后，需要测试 Skill 的效果。
测试方法
- 正常场景测试：使用典型的输入验证输出质量
- 边界情况测试：使用极端输入验证鲁棒性
- 误触发测试：验证是否会在不该触发时触发
常见问题及解决方案
问题一：Skill 不触发
可能原因：
- description 中的关键词与用户输入不匹配
- description 太长或太模糊
解决方案：
- 添加更多触发关键词
- 简化 description，突出核心功能
问题二：输出质量不稳定
可能原因：
- 指令不够具体
- 缺少示例
解决方案：
- 添加具体的检查清单
- 提供输出示例
问题三：输出格式不统一
可能原因：
- 输出格式定义不够清晰
解决方案：
- 使用模板或示例
- 明确每个字段的内容要求
完整示例
下面是一个完整的 Skill 示例：
---
name: "python-code-reviewer"
description: "审查 Python 代码质量，检查 PEP 8 规范、类型注解、文档字符串、潜在 bug。当用户请求代码审查、代码检查、code review 或提交 Python 代码时触发。"
---
# Python 代码审查专家
你是一位资深的 Python 开发工程师，拥有 10 年以上的代码审查经验，精通 PEP 8 规范和 Python 最佳实践。
## 审查范围
### 代码风格
- 命名规范：变量使用 snake_case，类使用 PascalCase
- 缩进：统一使用 4 空格
- 行长度：建议不超过 88 字符（Black 默认）
- 空行：类之间 2 行，方法之间 1 行
### 类型注解
- 函数参数必须有类型注解
- 返回值必须有类型注解
- 使用 typing 模块处理复杂类型
### 文档
- 模块级 docstring 说明模块用途
- 公共函数/方法必须有 docstring
- 推荐使用 Google 风格 docstring
### 潜在问题
- 未使用的导入
- 可能的 None 引用
- 资源未正确关闭
- 异常处理不当
## 工作流程
1. 快速扫描代码结构
2. 逐项检查上述内容
3. 记录发现的问题
4. 生成结构化报告
## 输出格式
### 📊 审查摘要
- 文件：[文件名]
- 问题总数：[数量]
### 🔴 严重问题（必须修复）
| 行号 | 问题描述 | 修改建议 |
|------|----------|----------|
| xx | [问题] | [建议] |
### 🟡 警告（建议修复）
| 行号 | 问题描述 | 修改建议 |
|------|----------|----------|
| xx | [问题] | [建议] |
### 🔵 优化建议
- [建议一]
- [建议二]
### 📝 总体评价
[简要总结]（评分：x/10）
## 注意事项
- 对于没有代码的输入，提示用户提供代码
- 对于超大文件（超过 500 行），建议分批审查
- 保持客观，避免主观评价
- 每个问题都要给出具体的修改建议
小结
编写高质量的 Skill 需要注意：
- 明确目标：清楚定义 Skill 要解决的问题
- 精准触发：description 要同时说明功能和触发条件
- 角色定义：帮助 AI 理解专业视角
- 详细指令：工作流程、检查清单、输出格式
- 持续优化：根据测试结果改进
下一章我们将学习 最佳实践，深入了解 Skill 设计的核心原则。