如何编写合格的AI工作流指令：提升编辑技能

如何编写一个合格的 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）：逐步操作指南
• 规则与约束：刚性要求与弹性建议
• 可选示例

三、触发条件设计原则：具体化与可判断性

触发条件必须具体且可判断，避免模糊或泛泛的描述。

核心原则：触发描述应明确回答「在什么场景下、在哪个动作之前或之后」。

四、Workflow 设计原则：步骤明确、分支处理与终止条件

4.1 步骤需明确且可执行

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

# 优秀写法
### Step 1: 读取文件
- 使用 Read 工具读取目标文件
- 若文件不存在，则提示用户并终止流程

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

4.2 嵌入决策分支处理多种情况

实际场景中存在多种可能性，Workflow 应预判并覆盖关键分支：

- 若文档字数少于 5000：直接返回全文
- 若文档字数达到 5000 及以上：返回大纲，询问用户具体章节

4.3 明确每个流程的终止条件

每个流程都需设定清晰的完成标准，防止 AI 陷入无限循环或过早终止。

4.4 设置用户确认节点确保安全

在涉及写入、修改、删除等不可逆操作之前，必须加入用户确认环节：

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

五、刚性 Skill 与弹性 Skill 的区别与适用场景

在 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