如何编写一个合格的 Skill：AI 工作流核心指令集指南
在 AI 工作流的实际应用中，Skill（技能指令）常常被误解。许多人将其与普通提示词（Prompt）混淆，导致写出的指令过于宽泛或模糊，AI 难以精准执行。实际上，Skill 的本质是一套结构化的行为指令集，它引导 AI 助手在特定场景下明确思考路径与行动步骤。接下来，我们将从结构、触发条件、工作流程到常见误区，逐一深入解析。
一、什么是 Skill？定义与核心概念
Skill 是一种结构化的行为指令集，专门用于指导 AI 助手（如 Claude Code）在特定场景下的思考与行动方式。它不同于普通的提示词（Prompt），而是一套完整且可复用的人工智能工作流程定义。
二、Skill 的文件结构：Frontmatter 与 Body
一个合格的 Skill 文件通常由两个关键部分组成：
1. Frontmatter（元信息区域）
---
name: skill-name
description: 用一句话概括触发时机与用途（AI 据此判断是否调用该 Skill）
---description 字段至关重要——AI 依据它判断是否调用该 Skill，因此必须清晰指定触发场景，避免笼统描述。例如，“Use when implementing any feature or bugfix, before writing code”远优于“Use when coding”。
2. Body（正文指令内容）
正文包含：
- 触发条件说明：明确何时触发
- 分步骤执行流程（Workflow）：逐步操作指南
- 规则与约束：刚性要求与弹性建议
- 可选示例
三、触发条件设计原则：具体化与可判断性
触发条件必须具体且可判断，避免模糊或泛泛的描述。
| 优质触发描述 | 不当触发描述 |
|---|---|
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 与弹性 Skill 的区别与适用场景
| Skill 类型 | 定义 | 最佳适用场景 | 典型示例 |
|---|---|---|---|
| 刚性（Rigid） | 每步必须严格遵守，不允许跳过或变通 | 有严格质量要求的流程（如 TDD、安全审查） | test-driven-development |
| 弹性（Flexible） | 提供原则和模板，可根据上下文灵活调整 | 创作类、设计类任务 | frontend-design |
在 Skill 正文中应明确标注属于刚性或弹性类型，以便 AI 准确理解执行规则。
六、常见错误及避坑指南：如何避免踩坑
❌ 错误一：description 设置过于宽泛
# 错误示例
description: Use when doing any task
# 正确示例
description: Use when completing implementation tasks, before committing or creating PRs❌ 错误二：Workflow 未包含异常处理逻辑
每个关键步骤都必须预设失败处理机制：
- 若调用失败，检查凭证是否有效，提示用户重新配置❌ 错误三：混淆「做什么」与「怎么做」
Skill 应专注于描述「如何做（how）」，而非重复「做什么（what）」，后者属于用户的职责。
❌ 错误四：步骤间未明确数据传递关系
需要清晰定义上一步的输出如何传递给下一步：
- Step 1 返回文档 ID → Step 2 使用该 ID 调用更新接口七、最简合格 Skill 示例：code-review-checklist
---
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
