如何书写一个合格的 Skill

一、什么是 Skill

Skill 是一种结构化的行为指令集，用于告诉 AI 助手（如 Claude Code）在特定场景下应该如何思考、如何行动。它不是普通的提示词（Prompt），而是一套完整的工作流程定义。

二、Skill 的文件结构

一个合格的 Skill 文件由两部分组成：

1. Frontmatter（元信息）

---
name: skill-name
description: 一句话说明触发时机和用途（这是 AI 判断是否调用的依据）
---

description 极为关键——AI 依赖它来决定是否调用该 Skill，应明确写出触发场景，而非泛泛描述功能。

2. Body（正文内容）

正文包含：

• 触发说明：明确列出何时触发
• Workflow：分步骤的执行流程
• 规则与约束：刚性要求 vs 弹性建议
• 示例（可选）

三、触发条件设计

触发条件应尽量具体、可判断，避免模糊表述。

原则：触发描述要回答「什么情况下、在什么动作之前/之后」。

四、Workflow 设计原则

4.1 步骤要明确、可执行

每一步都应是可操作的具体动作，而非模糊的方向指引：

# 好的写法
### Step 1: 读取文件
- 调用 Read 工具读取目标文件
- 若文件不存在，提示用户并终止

# 差的写法
### Step 1: 了解文件内容
- 先看看文件里有什么

4.2 包含决策分支

真实场景有多种情况，Workflow 需要覆盖关键分支：

- 若文档 < 5000 字：直接返回全文
- 若文档 ≥ 5000 字：返回大纲，询问用户要读哪个章节

4.3 明确终止条件

每个流程都应有清晰的完成标准，避免 AI 无限循环或过早退出。

4.4 用户确认节点

涉及写入、修改、删除等不可逆操作前，必须设置用户确认步骤：

### Step 3: 确认内容
- 将结构化内容展示给用户预览
- 等待用户确认后，再执行创建操作

五、刚性 Skill vs 弹性 Skill

在 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