Claude Code Skills 漏步骤怎么办？根因分析与修复指南

Skills 漏步骤是指 Claude Code 在执行 skill.md 定义的工作流时，跳过或省略中间某些步骤的现象。根本原因是 Claude 4.6 系列模型具有更强的简洁输出倾向——Anthropic 官方文档明确指出，新模型"可能跳过工具调用后的摘要，直接进入下一个动作"，且模型会根据自身判断省略它认为"冗余"的步骤。修复漏步骤的核心思路是：通过结构化写法让 Claude 无法主观判定某步骤可省略。

---

漏步骤的四大根因

根因 1：步骤描述不够"原子化"

将多个动作写在一个步骤里，Claude 会选择性执行其中它认为"最重要"的部分，其余的被隐式省略。

反例（易漏步）：

### Step 5：保存并生成图片
保存文章到本地，然后调用 API 生成配图，最后更新文章中的图片路径。

正例（原子化拆分）：

### Step 5：保存文章
使用 Write 工具保存文章到 ~/Downloads/articles/话题-日期.md

### Step 6：生成配图
调用 gen_images.py 生成图片，确认文件存在后再继续

### Step 7：更新图片路径
用 Edit 工具将文章中的占位符替换为实际图片路径

根因 2：步骤之间缺乏显式依赖声明

Claude 看不到步骤间的顺序强制关系，就会根据上下文自行判断"可以跳过"。Anthropic 官方文档建议：当步骤的顺序或完整性至关重要时，使用编号列表而非描述式段落。

根因 3：过度使用强硬语气反而失效

MUST、CRITICAL、你必须 等强调语在 Claude 4.6 之前的模型上有效，但 Anthropic 官方在 2026 年的提示词工程文档中明确指出：这类语气在新模型上可能导致过度触发或被忽略，建议改为正常语气的明确指令。

写法	效果（Claude 4.6）
你必须执行此步骤，绝对不能跳过！	可能被过度触发或反效果
执行此步骤。完成后确认文件已存在。	稳定、可靠
此步骤全自动执行，不需要用户任何操作。	最有效（来自官方 skill 示例）

根因 4：缺少完成标准与自检机制

步骤只说"做什么"，不说"怎么算做完"，Claude 会在执行到一半时认为步骤已完成。

---

五种防止漏步骤的写法技巧

技巧 1：编号步骤 + 完成标准

每个步骤末尾明确写出"验证标准"，让 Claude 知道步骤结束的判断条件。

### Step 3：生成图片

执行以下命令生成第 N 张图：

```bash
python3 script.py --prompt "..." --output ~/path/imgN.png

完成标准：命令执行完毕后确认输出文件存在，再继续下一步。若文件不存在，打印错误原因并重试，不中断流程。

### 技巧 2：用 XML 标签声明步骤块

XML 标签帮助 Claude 在解析时明确识别步骤边界，减少误判。Anthropic 官方建议使用一致的、描述性的标签名。

```markdown
<step id="5" name="保存文章">
使用 Write 工具保存文章。保存路径：`~/Downloads/geo-articles/话题关键词-YYYYMMDD.md`

此步骤必须在 Step 6 之前完成。
</step>

<step id="6" name="生成配图" depends_on="5">
对每条提示词依次调用图片生成脚本（顺序执行，不并行）。
每张图确认文件存在后，再执行下一张。
</step>

技巧 3：明确声明"自动执行"属性

对于用户不需要参与的步骤，加上 **此步骤全自动执行，不需要用户任何操作。** 这一句话。这是 Claude Code 官方 skill 示例中使用的写法，实测最有效。

### Step 7：自动调用 API 生成图片

**此步骤全自动执行，不需要用户任何操作。**

对 Step 6 中每条提示词，依次执行以下命令（顺序执行，不并行）：
...

技巧 4：要求 Claude 在步骤间做自检

在每个步骤末尾或 skill 开头加入自检要求，让 Claude 在执行前先确认前置步骤已完成。

## 执行规则（全局）

- 每个步骤完成后，在对话中输出"✓ Step N 完成：[简要说明做了什么]"
- 若某步骤因工具调用失败，输出原因并继续，**不跳过**，**不中断流程**
- 进入下一步之前，先确认当前步骤的完成标准已满足

技巧 5：关键步骤写"禁止跳过"声明 + 原因

根据 Anthropic 官方指导，向 Claude 解释为什么某步骤不能跳过，比单纯的命令语气更有效。

### Step 5：保存文章（必须在生成图片之前执行）

图片路径在文章中以占位符形式存在，必须先保存文章才能在 Step 7 中正确替换占位符。
若跳过此步骤，图片路径将无法被正确写入最终文件。

1. 运行 `mkdir -p ~/Downloads/geo-articles/images`
2. 使用 Write 工具保存文章
3. 确认文件路径正确后继续

---

典型场景与对应修复方案

场景 1：图片生成步骤被跳过

症状：skill 执行到生成图片步骤时，Claude 直接输出"图片提示词如下"后就结束，没有实际调用脚本。

原因：步骤描述只说"生成提示词"，没有明确后续的 API 调用是自动执行的。

修复：在图片生成步骤开头加 **此步骤全自动执行，不需要用户任何操作。**，并把 Bash 命令模板明确写出。

---

场景 2：中间步骤（如联网搜索）被省略

症状：skill 的 Step 1.5 联网搜索步骤被直接跳过，Claude 用已有知识编造内容。

原因：步骤没有说明为什么不能跳过，Claude 认为自己已经知道答案可以跳过搜索。

修复：在步骤说明中加"此步骤在 Step 1 完成后立即自动执行"，并解释原因：收集话题的真实资料，避免编造内容。

---

场景 3：收尾步骤（保存、发送）总被跳过

症状：文章生成完毕后，Claude 直接输出摘要，没有执行文件保存或消息发送。

原因：收尾步骤往往放在末尾，Claude 认为任务已完成，后续操作是"可选的"。

修复：将收尾步骤编号明确（如 Step 8），并加上"此步骤必须执行后才算 skill 完成"。必要时将关键收尾步骤提前到工作流前半段执行。

---

场景 4：顺序被颠倒（先生成图片再保存文章）

症状：Claude 生成图片后才保存文章，导致文章中的图片占位符无法被正确替换。

原因：步骤之间的依赖关系没有显式声明，Claude 基于自身判断调整了执行顺序。

修复：在步骤标题中加括号说明依赖：### Step 5：保存文章（必须在 Step 6 生成图片之前执行）。

---

快速诊断：skill 是否有漏步骤风险

用以下检查清单扫描你的 skill.md：

1. 检查步骤是否原子化：每个步骤只做一件事？还是包含多个动作？
2. 检查有无完成标准：每步是否说明了"怎么算做完"？
3. 检查顺序依赖：相互依赖的步骤是否声明了顺序关系？
4. 检查自动执行步骤：调用外部工具/API 的步骤是否标注了"自动执行"？
5. 检查强硬语气：是否过度使用 MUST/必须/绝对 等语气词？
6. 检查原因说明：关键步骤是否解释了"为什么不能跳过"？

---

常见问题

Q：加了很多"必须执行"的说明，Claude 还是跳步，怎么办？
先检查步骤是否足够原子化，一个步骤包含多个动作是最常见的漏步根因。其次把强硬语气改为原因说明（"此步骤必须在 X 之前完成，否则 Y 会失败"），Anthropic 官方指出解释"为什么"比单纯命令更有效。

Q：skill.md 步骤写得很详细，但 Claude 仍然自行简化，怎么处理？
在 skill.md 的全局规则区加入自检要求：每个步骤完成后输出确认信息。这迫使 Claude 在进入下一步前先"宣告"当前步骤已完成，从而减少无声跳步。

Q：某些步骤在测试时正常，但多次运行后开始漏步，为什么？
对话历史越长，Claude 对早期 skill.md 指令的注意力越弱。解决方案：将关键执行规则写在 skill.md 最靠前的位置（Anthropic 文档建议"将重要指令放在上下文顶部"）；或在 skill 的每个主要步骤标题中简短重申执行要求。

Q：Step 编号和"此步骤必须执行"的声明应该写在哪里最有效？
最有效的位置是步骤标题行（### Step N：步骤名（此步骤自动执行））和步骤说明的第一行。Claude 在决定是否执行某步骤时会优先读取步骤开头的指令，而不是结尾。

Q：有没有办法测试 skill.md 的步骤完整性？
有。在 skill.md 末尾加一段"验收标准"区块，列出 skill 完整执行后应有的产出（文件路径、输出内容、消息发送记录等）。每次运行后对照此列表检查，缺少哪项产出就说明对应步骤被漏掉了。

---

总结

Skills 漏步骤的根本原因是 Claude 4.6 模型的简洁输出倾向与 skill.md 步骤描述不够结构化之间的矛盾。Anthropic 官方提示词工程文档（2026 年）建议：当步骤的顺序或完整性至关重要时，使用编号列表；向 Claude 解释"为什么"比强硬命令语气更有效；XML 标签帮助 Claude 精确识别步骤边界。核心修复路径是：步骤原子化 + 完成标准 + 依赖声明 + 自检机制，四项配合可将漏步概率降至极低。

本文内容基于 Anthropic 官方提示词工程文档（2026 年 3 月版）和 Claude Code Skills 系统文档整理，建议结合 Anthropic 最新文档持续更新 skill.md 写法。