在设计包含多阶段校验的复杂技能时，如何合理组织 SKILL.md 中的 Markdown 工作流指令？

知识点图片

在设计包含多阶段校验（Multi-stage Validation）的复杂 Agent Skill 时，SKILL.md 的正文编写逻辑必须从传统的“描述性提示词（Descriptive Prompt）”转变为“确定性状态机（Deterministic State Machine）”或“严格的 SOP（标准作业程序）”。

大模型虽然聪明，但在超长或复杂任务中容易跳过步骤、遇到报错就放弃，或者陷入死循环。为了引导它完美执行多阶段校验，你需要通过合理的 Markdown 组织结构来约束它的“思维链（Chain of Thought）”。

以下是组织 SKILL.md 工作流指令的 4 个核心原则和 1 个标准模板样例：

核心原则 1：采用“阶段划分（Phases）”的线性结构

大模型对 Markdown 的层级结构（H1, H2, H3）非常敏感。不要用一大段长文混合说明，必须使用一级标题（#）或二级标题（##）将任务强行切割为独立的生命周期。
标准的复杂任务至少应包含四个阶段：

Phase 1: 准备与侦查（Reconnaissance）：收集必要信息，读取依赖文档。
Phase 2: 核心执行（Execution）：修改代码或生成内容。
Phase 3: 多阶段校验（Validation Gates）：这是重点。将校验拆分成独立的、有先后顺序的“关卡”。
Phase 4: 收尾与汇报（Finalization）：清理现场，按指定格式输出结果。

核心原则 2：明确定义“触发器”、“执行动作”与“纠错协议”

在校验阶段，你不仅要告诉 AI “校验什么”，更要明确告诉它“如何校验”和“失败了怎么办（Self-Correction Protocol）”。
使用“If...Then...”的确定性句式：

❌ 错误写法：“请确保代码没有 bug 并符合规范。”（太模糊，AI 会直接脑补说“我检查过了，没问题”）
✅ 正确写法：“阶段一校验：请运行 npm run lint。如果终端返回错误（If error），你必须分析具体的报错行数，修改代码，并重新运行该命令，直到输出完全通过（Then fix and retry）。”

核心原则 3：设定“最大重试次数（Max Retries）”以防死循环

多阶段校验极易导致 AI 陷入“修改 -> 报错 -> 盲目修改 -> 继续报错”的死循环，这会迅速耗尽 Token。必须在 Markdown 中硬性规定重试上限。

“对于每个校验阶段，最多允许重试 3 次。如果 3 次后仍未通过，请停止操作，还原代码，并向用户报告无法解决的原因。”

核心原则 4：善用复选框（Checklists）强化执行纪律

Markdown 的复选框（- [ ]）在提示词工程中有一种奇妙的“心理暗示”作用。大模型在看到复选框时，更倾向于严格按顺序逐一执行，而不是跳步。

👑 实战样例：一个标准的多阶段校验 `SKILL.md` 结构

假设我们要设计一个“深度代码重构与审查（Deep Refactoring）”的 Skill。它的 SKILL.md 正文应该这样组织：

plaintext

---
name: deep-refactor
description: 深度重构指定文件，并强制通过静态检查、单元测试和安全扫描三个阶段的校验。
---

# 角色设定
你是一个严谨的资深架构师。你的目标是重构用户指定的代码文件，并在提交前严格通过所有校验关卡。请严格按照以下步骤执行，不得跳过任何阶段。

# 执行步骤

## 阶段 1：上下文侦查 (Context Recon)
- [ ] 1. 使用 `read_file` 工具读取用户指定的目标文件。
- [ ] 2. 使用 `read_file` 读取 `references/coding-standard.md`，了解团队的代码规范。
- [ ] 3. 规划你的重构策略，并在内部思维链中简要说明。

## 阶段 2：核心代码重构 (Execution)
- [ ] 1. 使用 `edit_file` 工具将重构后的代码应用到目标文件中。

## 阶段 3：多阶段校验 (Multi-stage Validation Gates)
⚠️ 重要规则：你必须按顺序通过以下 3 个关卡。任何一个关卡失败，都必须立刻停下来修复，修复后重新从当前关卡开始。每个关卡最多允许重试 3 次。

### Gate 1: 静态类型与格式检查 (Linting & Formatting)
- 操作：在终端运行工具 `bash scripts/run_linter.sh`。
- 通过标准：退出码（Exit code）为 0，无任何 Error 级别报错。
- 失败协议：如果失败，请分析终端输出的具体行号，使用 `edit_file` 修复格式，然后重新运行本关卡。

### Gate 2: 单元测试回归 (Unit Tests Regression)
- 操作：在终端运行 `pytest tests/` (Python) 或 `npm test` (Node.js)。
- 通过标准：所有测试用例呈绿色/Passed状态。
- 失败协议：如果测试失败，仔细阅读 Assertion Error。修改你的重构逻辑（注意：绝不允许修改测试用例本身来迎合错误代码），修改后重新运行本关卡。

### Gate 3: 本地安全与依赖扫描 (Security Scan)
- 操作：运行 `python3 scripts/security_check.py`。
- 通过标准：终端输出 "Security Scan Passed" 字样。
- 失败协议：若发现高危函数（如未转义的 SQL 拼接），立即替换为安全的内置函数，并重新运行本关卡。

## 阶段 4：强制熔断与最终汇报 (Fallback & Reporting)
- 如果在任何 Gate 中 重试超过 3 次 依然失败：请停止修改！使用自然语言告诉用户：“重构失败，卡在 Gate X。报错信息如下：... 我已还原代码。”
- 如果 3 个 Gate 全部通过：请按照以下格式输出你的成功报告：
  ```text
  ✅ 重构完成并已通过多阶段校验！
  - 优化总结：[一句话总结你的修改]
  - 校验结果：Lint (通过) | Unit Test (通过) | Security (通过)

plaintext


### 为什么这种结构极其有效？
1. 防幻觉：AI 不再凭借自己的感觉判断“代码写得好不好”，而是必须依赖外部工具（`run_linter.sh`, `pytest`）的客观反馈。
2. 逻辑沙盒化：由于有了 `Gate 1/2/3` 的划分，如果 AI 在 Gate 2 单元测试卡住了，它会将所有的注意力（Attention）集中在排查测试失败的原因上，而不会去胡乱修改 Gate 1 中已经通过的语法格式。
3. 可预测性（Predictability）：由于引入了明确的“失败协议”和“重试 3 次”的熔断机制，AI 的行为变得完全可控，避免了在无人值守的情况下疯狂消耗 API 额度。

右滑查看面试常问

播面