如何书写一个合格的 Skill
一、什么是 Skill
Skill 是一种结构化的行为指令集，用于告诉 AI 助手（如 Claude Code）在特定场景下应该如何思考、如何行动。它不是普通的提示词（Prompt），而是一套完整的工作流程定义。
Skill 的核心价值：让 AI 在重复性任务中保持一致的高质量输出，避免每次都重新"摸索"流程。
二、Skill 的文件结构
一个合格的 Skill 文件由两部分组成：
1. Frontmatter（元信息）
---
name: skill-name
description: 一句话说明触发时机和用途（这是 AI 判断是否调用的依据）
---
description 极为关键——AI 依赖它来决定是否调用该 Skill，应明确写出触发场景，而非泛泛描述功能。
2. Body（正文内容）
正文包含：
- 触发说明：明确列出何时触发
- Workflow：分步骤的执行流程
- 规则与约束：刚性要求 vs 弹性建议
- 示例（可选）
三、触发条件设计
触发条件应尽量具体、可判断，避免模糊表述。
| 好的触发描述 | 差的触发描述 |
|---|---|
Use when implementing any feature or bugfix, before writing code | Use when coding |
Triggers when user pastes a Feishu URL and asks to read/summarize | Use with Feishu |
Use when about to claim work is complete, before committing | Use at end of task |
原则：触发描述要回答「什么情况下、在什么动作之前/之后」。
四、Workflow 设计原则
4.1 步骤要明确、可执行
每一步都应是可操作的具体动作，而非模糊的方向指引：
# 好的写法
### Step 1: 读取文件
- 调用 Read 工具读取目标文件
- 若文件不存在，提示用户并终止
# 差的写法
### Step 1: 了解文件内容
- 先看看文件里有什么
4.2 包含决策分支
真实场景有多种情况，Workflow 需要覆盖关键分支：
- 若文档 < 5000 字：直接返回全文
- 若文档 ≥ 5000 字：返回大纲，询问用户要读哪个章节
4.3 明确终止条件
每个流程都应有清晰的完成标准，避免 AI 无限循环或过早退出。
4.4 用户确认节点
涉及写入、修改、删除等不可逆操作前，必须设置用户确认步骤：
### Step 3: 确认内容
- 将结构化内容展示给用户预览
- 等待用户确认后，再执行创建操作
五、刚性 Skill vs 弹性 Skill
| 类型 | 含义 | 适用场景 | 示例 |
|---|---|---|---|
| 刚性（Rigid） | 每步必须严格遵守，不允许跳过或变通 | 有严格质量要求的流程（如 TDD、安全审查） | test-driven-development |
| 弹性（Flexible） | 提供原则和模板，可根据上下文灵活调整 | 创作类、设计类任务 | frontend-design |
在 Skill 正文中应明确声明属于哪种类型，帮助 AI 正确理解执行约束。
六、常见错误与避坑指南
❌ 错误 1：description 过于宽泛
# 错误
description: Use when doing any task
# 正确
description: Use when completing implementation tasks, before committing or creating PRs
❌ 错误 2：Workflow 缺少异常处理
每个关键步骤都应考虑失败场景：
- 若调用失败，检查凭证是否有效，提示用户重新配置
❌ 错误 3：把「what」和「how」混在一起
Skill 应该专注描述「how（如何做）」，而不是重复描述「what（做什么）」——那是用户的职责。
❌ 错误 4：步骤之间缺乏数据流说明
明确上一步的输出如何传递给下一步：
- Step 1 返回文档 ID → Step 2 使用该 ID 调用更新接口
七、一个最简合格 Skill 示例
---
name: code-review-checklist
description: Use after finishing a feature implementation, before creating a PR - runs a structured review checklist
---
## Trigger
- After finishing implementation of a feature or bugfix
- Before creating a pull request
## Workflow
### Step 1: 读取变更
- 执行 `git diff main` 获取所有变更
- 列出涉及的文件清单
### Step 2: 逐项检查
按以下清单检查每个变更文件：
- [ ] 是否有未处理的异常？
- [ ] 是否存在硬编码的敏感信息？
- [ ] 新增代码是否有对应测试？
- [ ] 是否影响现有接口的兼容性？
### Step 3: 输出报告
- 对每个问题给出具体文件和行号
- 区分「必须修复」和「建议优化」两类
- 所有「必须修复」项解决后，方可创建 PR
