复杂 Skill 不能继续堆长 prompt，真正稳定的做法是显式建模状态、边界和检查点。
原文链接：AI 小老六
一个 Skill 写到后期，真正拖垮它的往往不是模型能力，而是状态混在一起。入口、执行阶段、校验规则、失败恢复和局部修改全塞进一个长 prompt，短期能跑，长期一定会变成谁都不敢碰的流程泥团。
更稳的做法，是把复杂 Skill 当成一个小型状态机来设计。Mode 决定它处在哪个生命周期，Step 决定它此刻只该做哪一件事。模型不再被要求在一整份长文档里记住所有分支，而是一次只进入一个边界清楚、产物明确、可以验收的小状态。
很多 Skill 一开始都很朴素：读输入、分析、调用脚本、生成结果、做一次校验。第一次上线时，一个 workflow.md 足够清楚。真正的麻烦通常发生在后面：用户要重跑校验、只改某个结论、从中断处恢复，维护者于是不断往同一个文件里加 if create、if validate、if edit、if resume。
这时继续补一句“不要跳过步骤”或者“验证阶段禁止修改文件”，效果很有限。模型看到的仍然是一团混合状态：它同时知道生成链路、验证链路、编辑链路和恢复链路，也就容易在该只读的时候顺手修复，在该局部修改的时候重新生成全文。
长 prompt 失控，本质不是文字太多，而是生命周期、权限和完成条件混在了同一层。
图：长 workflow 中的状态混杂如何导致边界失控。
| 失控迹象 | 常见补丁 | 更底层的原因 |
|---|---|---|
| 模型跳过中间步骤 | 反复强调“必须逐步执行” | 每一步没有独立完成条件，也没有明确的下一跳 |
| Validate 阶段顺手修复 | 再写一条“只读”规则 | 验证和编辑共享同一上下文，边界只靠自然语言提醒 |
| 中途失败只能从头跑 | 让模型重新读取全部材料 | 进度没有外化，产物也没有检查点 |
| 文件越写越长 | 继续追加分支说明 | 入口路由、执行逻辑、校验门禁被放在同一层 |
判断一个 Skill 是否需要升级，不看它有多少行 prompt，而看它是否已经拥有多个生命周期。如果同一个入口既要创建、又要校验、还要局部编辑或续跑，那么它已经不是“提示词写得更细”能解决的问题。
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 不是把长 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 模拟一个没有显式建模的状态机。
迁移不必一步到位。最稳的做法，是先保留原来的用户入口，只把 Create 主链路切成几个 Step。这样用户行为不变，维护者却能立刻获得更短的上下文和更清楚的执行边界。
图：迁移旧 Skill 时，先切主链路，再隔离校验和检查点，风险最低。
| 迁移阶段 | 具体做法 | 为什么这样风险低 |
|---|---|---|
切出 steps-c/ |
把原有主流程拆成输入收集、分析、生成几个 Step | 不改变入口，只降低单步复杂度 |
| 增加检查点 | 给产物写 stepsCompleted、changelog 或 sentinel |
Resume 有了事实依据，不靠模型记忆 |
隔离 steps-v/ |
把重新校验从 Create 中拿出来 | Validate 的只读边界最容易被污染，值得优先隔离 |
补 steps-e/ |
在真实出现局部返工后再设计编辑路径 | Edit 的边界来自实际场景，过早设计容易空泛 |
从设计顺序看，不要先问“我要建几个 Step 文件”。先问最终产物是什么、哪些错误不能发生、失败时如何发现、哪些逻辑可以脚本化。Step 只是承载这些约束的容器。
写复杂 Skill 前，可以先做一轮很短的设计检查：
最小可行改造其实不重：一个入口 workflow.md，一条 steps-c/ 主链路，再加一条只读的 steps-v/ 校验链路，通常就能明显减少跳步、越界和失败后重跑的问题。Resume 和 Edit 可以等真实返工场景出现后再补，不必一开始就把所有未来情况设计完。
Prompt 思维经常问：“我还要告诉模型什么？”Workflow 思维会先问：“模型此刻处在哪个状态，它能读什么，不能做什么，完成后转移到哪里？”
这两个问题不是同一层级。复杂 Skill 的稳定性，来自状态显式化、边界契约化、检查点外化和门禁脚本化。长 prompt 能把规则写进去，但很难保证模型在正确的时间只使用正确的那一部分。Mode-Step 网格的价值，就在于把这些隐含状态拆开，让模型不用每次都重新猜。
业务 Agent 搭建指南：别急着重造 Agent，用知识、工具与评测跑通闭环
Dynamic Workflows 深度解析：Claude Code 为什么把多 Agent 编排写进可执行代码
AI Coding 如何影响交付链路重构：写代码更快了，为什么人反而觉得更累了？
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。