Agent Skill 状态机工程：Mode-Step 网格如何拆开工作流边界

复杂 Skill 不能继续堆长 prompt，真正稳定的做法是显式建模状态、边界和检查点。
原文链接：AI 小老六

一个 Skill 写到后期，真正拖垮它的往往不是模型能力，而是状态混在一起。入口、执行阶段、校验规则、失败恢复和局部修改全塞进一个长 prompt，短期能跑，长期一定会变成谁都不敢碰的流程泥团。

更稳的做法，是把复杂 Skill 当成一个小型状态机来设计。Mode 决定它处在哪个生命周期，Step 决定它此刻只该做哪一件事。模型不再被要求在一整份长文档里记住所有分支，而是一次只进入一个边界清楚、产物明确、可以验收的小状态。

先识别问题：长 prompt 失控不是文字问题

很多 Skill 一开始都很朴素：读输入、分析、调用脚本、生成结果、做一次校验。第一次上线时，一个 workflow.md 足够清楚。真正的麻烦通常发生在后面：用户要重跑校验、只改某个结论、从中断处恢复，维护者于是不断往同一个文件里加 if create、if validate、if edit、if resume。

这时继续补一句“不要跳过步骤”或者“验证阶段禁止修改文件”，效果很有限。模型看到的仍然是一团混合状态：它同时知道生成链路、验证链路、编辑链路和恢复链路，也就容易在该只读的时候顺手修复，在该局部修改的时候重新生成全文。

长 prompt 失控，本质不是文字太多，而是生命周期、权限和完成条件混在了同一层。

图：长 workflow 中的状态混杂如何导致边界失控。

失控迹象	常见补丁	更底层的原因
模型跳过中间步骤	反复强调“必须逐步执行”	每一步没有独立完成条件，也没有明确的下一跳
Validate 阶段顺手修复	再写一条“只读”规则	验证和编辑共享同一上下文，边界只靠自然语言提醒
中途失败只能从头跑	让模型重新读取全部材料	进度没有外化，产物也没有检查点
文件越写越长	继续追加分支说明	入口路由、执行逻辑、校验门禁被放在同一层

判断一个 Skill 是否需要升级，不看它有多少行 prompt，而看它是否已经拥有多个生命周期。如果同一个入口既要创建、又要校验、还要局部编辑或续跑，那么它已经不是“提示词写得更细”能解决的问题。

Mode-Step 网格：把生命周期和执行步骤分开

Tri-Modal Step File 的核心可以压成一句话：外层按 Mode 分生命周期，内层按 Step 分执行阶段。Agent 先进入某个 Mode，再加载该 Mode 下的当前 Step File。每个文件只承担一段很窄的职责。

换句话说，Mode 管生命周期，Step 管当前动作。这两个维度拆开以后，生成、校验、编辑、续跑才不会在同一份提示词里互相污染。

图：Mode-Step 网格把生命周期和当前动作拆开，让模型只进入一个窄边界状态。

图：Mode 管生命周期，Step 管当前执行阶段。

Mode	典型目录	适合处理的意图	必须守住的边界
Create	`steps-c/`	从零读取上下文、分析材料、生成目标产物	可以创建新 artifact，但要按 Step 前进
Validate	`steps-v/`	对已有产物做重新校验、覆盖率检查、差异核对	默认只读，只输出 `PASS / CONCERNS / FAIL`
Edit	`steps-e/`	针对某个章节、规则、finding 做局部修改	先评估影响范围，再做定点替换，避免重生成
Resume	通常不单独成目录	读取 frontmatter、sentinel 或日志，判断从哪里继续	只负责路由，不承担业务执行

这个拆法的好处很实际：新增一次局部编辑能力，不必去改 Create 主链路；补一个重新校验规则，也不会把生成逻辑搅乱。维护者先找 Mode，再找 Step，改动范围通常会小很多。

Step File：给模型一个局部执行契约

Step File 不是把长 prompt 切成几段那么简单。它更像一份小契约，告诉模型：这一步唯一目标是什么，可以看哪些上下文，哪些事情绝对不能做，执行顺序是什么，怎样算完成，完成后去哪里。

图：Step File 像一份局部执行契约，把目标、边界、顺序和验收条件钉住。

图：一个 Step File 应同时约束目标、边界、顺序、验收和下一跳。

一个可维护的 Step File 至少应该写清这些内容：

契约字段	解决的问题	写作要点
`STEP GOAL`	防止模型在本步做太多事	用一句话说清本步唯一目标
`MANDATORY RULES`	固定必须遵守的纪律	少而硬，不写泛泛的价值观
`CONTEXT BOUNDARIES`	防止上下文外溢	明确可读材料、可写文件和禁止动作
`MANDATORY SEQUENCE`	防止跳步	写成可执行顺序，不写抽象建议
`SUCCESS CRITERIA`	让步骤可验收	用可判断的完成条件，不用“尽量完善”
`NEXT STEP`	让状态可转移	成功、失败、需人工介入时分别去哪

目录结构也不需要复杂，关键是让人一眼看出生命周期和步骤边界：

skills/<your-skill>/
├── SKILL.md
├── workflow.md
├── workflow.yaml
├── steps-c/
│   ├── step-01-gather-inputs.md
│   ├── step-02-analyze.md
│   └── step-03-generate-output.md
├── steps-v/
│   └── step-01-validate.md
├── steps-e/
│   └── step-01-assess-and-edit.md
├── scripts/
├── references/
└── templates/

其中 workflow.md 不应该继续承载业务细节。它只做初始化、参数优先级处理、预检查、模式判断和首步路由。确定性逻辑尽量放进 scripts/，比如解析输入、做 diff、检查格式、统计覆盖率、渲染报告。LLM 更适合做语义理解、归纳和取舍，不适合靠记忆执行一堆机械门禁。

按状态加载：不是少读上下文，而是读对上下文

Step File 经常被误解成“减少上下文”。减少当然有价值，但更关键的是按状态加载上下文。普通渐进式加载是按需读资料，主要缓解 token 压力；Mode-Step 加载是先判断状态，再读取这个状态需要的材料，目标是压住边界漂移。

图：Mode-Step 加载不是少读上下文，而是按状态读取正确上下文。

当 Agent 知道自己处在 Validate / step-02-check，它就不需要同时携带 Create 的生成细则和 Edit 的替换策略。它只需要读校验输入、执行检查、输出结论。边界越窄，模型越不容易“热心过头”。

这种设计还会自然带来检查点。每个 Step 的输出可以写入 artifact frontmatter、状态文件或 sentinel。下一次 Resume 不是让模型猜“我上次做到哪了”，而是读取状态记录，再回到对应 Mode 的对应 Step。

图：Step 输出、检查点和 Gate 共同支撑续跑与失败恢复。

什么时候值得上，什么时候别上

这个模式不是默认模板。一次性问答、单脚本调用、输入输出都很单一的小工具，没必要套一层工程结构。越早过度工程化，越容易把简单问题写复杂。

更好的触发信号是：流程已经出现第二个生命周期，或者失败后重跑成本明显变高。比如同一个 Skill 既要生成长期产物，又要允许后续校验和局部修订；或者它需要多人维护，PR 里经常有人看不出到底该改哪段规则。

适合使用 Mode-Step	不适合使用 Mode-Step
同一个 Skill 同时支持生成、校验、编辑、恢复	一次性问答或一次性改写
有 3 个以上连续步骤，且每步有中间产物	两三句话就能说清的小工具
输入来源复杂，需要参数优先级和缺失处理	输入单一、输出单一、失败成本低
流程可能中断，需要从中间继续	没有中间状态，也不沉淀 artifact
多人长期维护，需要明确修改边界	短期实验性 prompt

一个很实用的判断是：如果你已经在 workflow.md 里写了第二条 if mode == ...，就该停一下。继续往下堆分支并不是不行，但那通常意味着你正在用 prompt 模拟一个没有显式建模的状态机。

从旧 Skill 迁移：先切主链路，再隔离校验

迁移不必一步到位。最稳的做法，是先保留原来的用户入口，只把 Create 主链路切成几个 Step。这样用户行为不变，维护者却能立刻获得更短的上下文和更清楚的执行边界。

图：迁移旧 Skill 时，先切主链路，再隔离校验和检查点，风险最低。

迁移阶段	具体做法	为什么这样风险低
切出 `steps-c/`	把原有主流程拆成输入收集、分析、生成几个 Step	不改变入口，只降低单步复杂度
增加检查点	给产物写 `stepsCompleted`、`changelog` 或 sentinel	Resume 有了事实依据，不靠模型记忆
隔离 `steps-v/`	把重新校验从 Create 中拿出来	Validate 的只读边界最容易被污染，值得优先隔离
补 `steps-e/`	在真实出现局部返工后再设计编辑路径	Edit 的边界来自实际场景，过早设计容易空泛

从设计顺序看，不要先问“我要建几个 Step 文件”。先问最终产物是什么、哪些错误不能发生、失败时如何发现、哪些逻辑可以脚本化。Step 只是承载这些约束的容器。

落地前的工程检查

写复杂 Skill 前，可以先做一轮很短的设计检查：

最终产物的路径、格式、更新方式是否明确。
用户会触发哪些生命周期，Create / Validate / Edit / Resume 是否需要分开。
上下文来源是否有优先级，显式参数、本地配置、自动探测和询问用户的顺序是否固定。
每个 Step 是否只有一个目标，是否写明本步不能做什么。
失败后能否从某个 Step 恢复，而不是从头重跑。
解析、格式校验、覆盖率、diff、渲染这些确定性工作，是否已经尽量下沉到脚本。
Validate 是否只读，Edit 是否局部，Create 是否不会偷偷承担校验修复职责。
每个 Step 末尾是否有明确的下一跳或完成标记。

最小可行改造其实不重：一个入口 workflow.md，一条 steps-c/ 主链路，再加一条只读的 steps-v/ 校验链路，通常就能明显减少跳步、越界和失败后重跑的问题。Resume 和 Edit 可以等真实返工场景出现后再补，不必一开始就把所有未来情况设计完。

结语：别让模型猜状态

Prompt 思维经常问：“我还要告诉模型什么？”Workflow 思维会先问：“模型此刻处在哪个状态，它能读什么，不能做什么，完成后转移到哪里？”

这两个问题不是同一层级。复杂 Skill 的稳定性，来自状态显式化、边界契约化、检查点外化和门禁脚本化。长 prompt 能把规则写进去，但很难保证模型在正确的时间只使用正确的那一部分。Mode-Step 网格的价值，就在于把这些隐含状态拆开，让模型不用每次都重新猜。

AI小老六