跳到主要内容

编写 Skills

编写高质量的 Skill 需要理解 AI 如何解读指令，以及如何设计清晰的工作流程。本章将详细介绍编写 Skill 的核心技巧。

从真实专业经验出发​

编写有效 Skill 的一个常见误区是让 LLM 在没有提供领域特定上下文的情况下生成 Skill——仅依赖 LLM 的一般训练知识。结果是模糊、通用的流程（如"适当处理错误"、"遵循认证最佳实践"），而不是具体的 API 模式、边界情况和项目约定。有效的 Skill 必须基于真实的专业经验。

从实际任务中提取​

在与 Agent 协作完成真实任务的过程中，提供上下文、纠正和偏好，然后提取可复用的模式。关注以下方面：

  • 成功的步骤——导致成功的操作序列
  • 你做的纠正——你引导 Agent 方法的地方（如"用库 X 代替 Y"，"检查边界情况 Z"）
  • 输入/输出格式——数据进出时的样子
  • 你提供的上下文——Agent 不知道的项目特定事实、约定或约束

从现有项目文档中综合​

当你有现有的知识体系时，可以将其输入 LLM 并要求综合成一个 Skill。从团队实际事故报告和运维手册综合的数据管道 Skill，将优于从通用"数据工程最佳实践"文章综合的 Skill，因为它捕获了你的模式、故障模式和恢复程序。

好的源材料包括：

  • 内部文档、运维手册和风格指南
  • API 规范、模式和配置文件
  • 代码审查评论和问题跟踪器（捕获重复关注点和审查者期望）
  • 版本控制历史，特别是补丁和修复（通过实际变更揭示模式）
  • 真实的故障案例及其解决方案

第一步：明确目标​

在开始编写之前，先回答以下问题：

  • 这个 Skill 解决什么具体问题？
  • 目标用户是谁？
  • 期望的输出是什么？
  • 有哪些边界情况需要处理？

示例：代码审查 Skill​

假设我们要编写一个代码审查 Skill，目标定义如下：

问题：团队代码审查标准不一致，经常遗漏关键问题
目标用户：开发团队成员
期望输出：结构化的审查报告，包含问题列表和改进建议
边界情况：空文件、超大文件、非代码文件

第二步：设计触发条件​

description 字段决定了 Skill 何时被触发，这是最关键的设计决策之一。

触发条件设计原则​

原则一：明确功能范围

❌ 太宽泛
description: "帮助处理代码相关的问题"

✅ 明确范围
description: "审查 Python 代码质量，检查命名规范、类型注解、文档字符串。当用户请求代码审查或提交 Python 代码时触发。"

原则二：包含触发关键词

AI 会根据用户输入和 description 的匹配度决定是否触发 Skill。因此，description 中应包含用户可能使用的关键词。

用户可能的说法：
- "帮我审查这段代码"
- "检查一下这个 Python 文件"
- "代码 review"

对应的 description：
description: "审查 Python 代码质量...当用户请求代码审查、代码检查、代码 review 或提交 Python 代码时触发。"

原则三：使用祈使语气

description 会被注入到系统提示中，作为给 Agent 的指令。使用祈使语气（如 "Use this skill when..."）可以让 Agent 更清楚地理解何时应该激活这个 Skill。一致的视角有助于 Agent 做出正确判断。

# 正确（祈使语气）
description: "Generate unit tests for code. Use when the user needs tests or test coverage."

# 错误（第三人称描述）
description: "这个技能帮助生成测试。当需要测试时使用它。"

中英文混合示例：

# 中文（祈使语气）
description: "审查 Python 代码质量，检查 PEP 8 规范。当用户请求代码审查时使用此技能。"

# 英文（祈使语气）
description: "Review Python code quality for PEP 8 compliance. Use when the user requests code review or submits Python code."

原则四：避免过度触发

❌ 可能过度触发
description: "处理所有 Python 相关问题"

✅ 精准触发
description: "审查 Python 代码质量...当用户明确请求代码审查时触发，不适用于代码编写或调试场景。"

测试触发准确性​

为了确保 description 正确触发，建议系统化测试：

设计测试查询

创建一组测试查询，分为两类：

{
  "queries": [
    {
      "prompt": "请审查这段代码",
      "should_trigger": true
    },
    {
      "prompt": "帮我写一个 Python 函数",
      "should_trigger": false
    },
    {
      "prompt": "检查这个文件的代码质量",
      "should_trigger": true
    },
    {
      "prompt": "这段代码有什么问题",
      "should_trigger": true
    }
  ]
}

Train/Validation 分割

为了避免过拟合，将查询分为训练集（60%）和验证集（40%）：

  • 用训练集识别失败并指导改进
  • 用验证集检查改进是否泛化

多次运行

模型行为具有非确定性，同一个查询可能有时触发有时不触发。建议：

  • 每个查询运行 3 次
  • 计算触发率：触发次数 / 总运行次数
  • 触发率 > 0.5 算作通过

迭代优化循环

  1. 在训练集和验证集上评估当前 description
  2. 识别训练集中的失败案例
  3. 修订 description（泛化问题而非添加特定关键词）
  4. 重复直到训练集通过率满意
  5. 选择验证集通过率最高的版本

第三步：定义角色​

角色定义帮助 AI 理解它应该具备的专业视角和判断标准。

命名规范​

选择一个好的 Skill 名称很重要。官方推荐使用动名词形式（gerund form），即动词 + -ing：

✅ 好的命名（动名词形式）
processing-pdfs
analyzing-spreadsheets
managing-databases
testing-code
writing-documentation

✅ 可接受的替代形式
pdf-processing, spreadsheet-analysis
process-pdfs, analyze-spreadsheets

❌ 应避免的命名
helper, utils, tools              # 太通用
documents, data, files            # 没有动作含义
anthropic-helper, claude-tools    # 不必要的品牌关联

一致命名的好处：

  • 更容易查找和引用
  • 清晰描述 Skill 的能力
  • 在对话中自然地提及

角色定义模板​

# [角色名称]

你是一位专业的 [职业身份]，精通 [核心技能]。

## 专业背景
- [相关经验]
- [专业领域]

## 核心原则
- [原则一]
- [原则二]

示例​

# Python 代码审查专家

你是一位资深的 Python 开发工程师，拥有 10 年以上的代码审查经验，精通 PEP 8 规范和 Python 最佳实践。

## 专业背景
- 参与过多个大型 Python 项目的代码审查
- 熟悉 Django、FastAPI、Flask 等主流框架
- 对性能优化和代码可维护性有深入理解

## 核心原则
- 代码首先是给人看的，其次才是给机器执行的
- 一致性比个人偏好更重要
- 每条建议都应该有理有据

第四步：编写指令​

指令是 Skill 的核心内容，需要详细描述工作流程和输出要求。

指令结构​

一个完整的指令通常包含以下部分：

## 工作流程

### 第一步：[步骤名称]
[详细描述]

### 第二步：[步骤名称]
[详细描述]

## 检查清单

- [ ] 检查项一
- [ ] 检查项二

## 输出格式

[输出模板]

## 注意事项

- [注意点一]
- [注意点二]

工作流程示例​

## 工作流程

### 第一步：快速扫描
快速浏览代码，识别明显的问题：
- 语法错误
- 导入问题
- 明显的逻辑错误

### 第二步：详细审查
逐项检查以下内容：

#### 代码风格
- 命名是否符合 PEP 8 规范
- 缩进是否一致（4 空格）
- 行长度是否超过 88 字符

#### 类型注解
- 函数参数是否有类型注解
- 返回值是否有类型注解
- 类型注解是否正确

#### 文档
- 模块级 docstring 是否存在
- 函数/方法 docstring 是否存在
- docstring 格式是否规范

### 第三步：生成报告
按照输出格式整理审查结果。

输出格式定义​

清晰的输出格式让结果更易读、更专业：

## 输出格式

请按以下格式输出审查结果：

### 📊 审查摘要
- 文件：[文件名]
- 总行数：[行数]
- 问题数量：[数量]

### 🔴 严重问题
[列出可能导致错误的问题]

### 🟡 警告
[列出代码风格问题]

### 🔵 建议优化
[列出优化建议]

### ✅ 改进建议
[针对主要问题给出具体修改方案]

### 📝 总体评价
[简要总结代码质量，给出评分 1-10]

第五步：测试优化​

编写完成后，需要测试 Skill 的效果。

测试方法​

  1. 正常场景测试：使用典型的输入验证输出质量
  2. 边界情况测试：使用极端输入验证鲁棒性
  3. 误触发测试：验证是否会在不该触发时触发

常见问题及解决方案​

问题一：Skill 不触发

可能原因：

  • description 中的关键词与用户输入不匹配
  • description 太长或太模糊

解决方案：

  • 添加更多触发关键词
  • 简化 description，突出核心功能

问题二：输出质量不稳定

可能原因：

  • 指令不够具体
  • 缺少示例

解决方案：

  • 添加具体的检查清单
  • 提供输出示例

问题三：输出格式不统一

可能原因：

  • 输出格式定义不够清晰

解决方案：

  • 使用模板或示例
  • 明确每个字段的内容要求

问题四：验证失败

可能原因：

  • name 与目录名不匹配
  • name 包含非法字符
  • description 为空或过长

解决方案：

  • 使用 npx skills-ref validate ./my-skill 验证
  • 确保 name 与目录名一致
  • 确保 description 符合规范（1-1024 字符）

完整示例​

下面是一个完整的 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 的每个部分都需要相同程度的指令性。根据任务的脆弱性匹配指令的具体程度。

给 Agent 自由度​

当多种方法都有效且任务可以容忍变化时，使用灵活的指令：

## 代码审查流程

1. 分析代码结构和组织
2. 检查潜在的 bug 或边界情况
3. 建议可读性和可维护性改进
4. 验证是否遵循项目约定

给予明确指令​

当操作脆弱、一致性重要或必须遵循特定顺序时：

## 数据库迁移

严格运行此脚本：
```bash
python scripts/migrate.py --verify --backup

不要修改命令或添加额外参数。


#### 提供默认值而非菜单

当多种工具或方法都可能有效时，选择一个默认值并简要提及替代方案，而不是将它们作为同等选项呈现：

```markdown
## 数据分析

使用 pandas 进行数据分析（可用 polars 作为高性能替代）：

# 默认推荐 pandas，但也承认 polars 的存在

指令模式​

以下是一些可复用的指令结构技术：

易错点清单​

许多 Skill 中最有价值的内容是易错点清单——特定环境的事实，它们违背了合理的假设：

## 常见陷阱

- **API 超时**：此 API 在高负载时会超时。实现指数退避重试，初始延迟 1 秒，最大 30 秒。
- **时区问题**：服务器返回 UTC 时间戳。必须在显示前转换为用户本地时区。
- **空值处理**：`get_user()` 在用户不存在时返回 `None` 而非抛出异常。始终检查返回值。

将这些内容放在 SKILL.md 中，让 Agent 在遇到情况之前就读到它们。

验证循环​

指示 Agent 在继续之前验证自己的工作：

## 工作流程

1. 执行任务
2. 运行验证器（脚本、检查清单或自检）
3. 修复发现的问题
4. 重复直到验证通过

计划-验证-执行​

对于批量或破坏性操作，让 Agent 先创建中间计划，验证后再执行：

## 批量操作流程

1. **计划**：生成将要执行的操作列表，输出到 plan.json
2. **验证**：将计划与源数据进行比对，确认没有遗漏或错误
3. **执行**：用户确认后，按计划执行操作

模板模式​

当需要 Agent 产生特定格式的输出时，提供模板比用文字描述格式更可靠。Agent 能很好地匹配具体的结构模式。

## 输出模板

使用以下格式输出审查结果：

## 审查报告

**文件**: `<filename>`
**日期**: `<date>`
**审查者**: AI Code Reviewer

### 问题摘要
| 严重程度 | 数量 |
|----------|------|
| 严重 | `<critical_count>` |
| 警告 | `<warning_count>` |
| 建议 | `<suggestion_count>` |

### 详细问题
- **[严重程度]** 第 行：问题描述
  - 建议：修改建议

### 总体评价
`<overall_assessment>`

短模板可以直接内联在 SKILL.md 中；长模板或只在特定情况下需要的模板，可以存储在 assets/ 目录中，从 SKILL.md 引用，这样只在需要时才加载。

检查清单模式​

对于多步骤工作流，显式的检查清单帮助 Agent 跟踪进度并避免跳过步骤，特别是当步骤有依赖关系或验证门时。

## 发布检查清单

在发布前，确认以下所有项目：

### 代码质量
- [ ] 所有测试通过
- [ ] 代码覆盖率 ≥ 80%
- [ ] 无安全漏洞警告

### 文档
- [ ] CHANGELOG.md 已更新
- [ ] API 文档已同步
- [ ] README.md 示例代码可运行

### 发布准备
- [ ] 版本号已更新
- [ ] Git 标签已创建
- [ ] 发布说明已准备

### 发布后验证
- [ ] 生产环境部署成功
- [ ] 健康检查通过
- [ ] 监控指标正常

子代理委托（高级模式）​

这是一个只被部分客户端支持的高级模式。不是将 Skill 指令注入主对话，而是在独立的子代理会话中运行 Skill。子代理接收 Skill 指令，执行任务，然后将工作摘要返回主对话。

适用场景：

  • Skill 的工作流足够复杂，受益于专门的、集中的会话
  • 需要隔离上下文的任务（如大规模代码分析）
  • 长时间运行的批处理任务

注意：这个功能需要特定的客户端支持，目前 Claude Code 等工具支持此功能。

与模型配合​

Skill 是模型的补充，因此效果取决于底层模型。计划使用的所有模型都要测试你的 Skill。

不同模型的测试考虑：

  • Opus/高级模型：理解能力强，可能需要更少的细节
  • Haiku/轻量模型：可能需要更明确的步骤和示例
  • 跨模型兼容：如果计划在多个模型上使用 Skill，编写对所有模型都适用的指令

小结​

编写高质量的 Skill 需要注意：

  1. 明确目标：清楚定义 Skill 要解决的问题
  2. 从真实经验出发：基于实际任务和项目文档编写
  3. 精准触发：description 要同时说明功能和触发条件，使用第三人称
  4. 命名规范：使用动名词形式（如 processing-pdfs），保持一致性
  5. 角色定义：帮助 AI 理解专业视角
  6. 详细指令：工作流程、检查清单、输出格式
  7. 控制度校准：根据任务脆弱性调整指令具体程度
  8. 易错点清单：列出环境特定的陷阱和边界情况
  9. 持续优化：根据真实执行反馈改进
  10. 多模型测试：在所有计划使用的模型上测试 Skill

下一章我们将学习 最佳实践，深入了解 Skill 设计的核心原则。