Skill 负责编排判断，CLI 稳定交付的执行边界

变成文档并不难，难的是让它在第二次、第三次使用时仍然靠谱。原因通常不在"知识没写下来"，而在下面这些地方：

判断和执行混在一起，谁都说不清哪一步可以自动化，哪一步必须停下来确认。
关键细节散在脚本、接口文档、聊天记录和某个人的习惯里，换一台机器就跑不动。
一旦失败，只能看到一句报错，却不知道卡在鉴权、参数、网络还是资源权限。
同一套能力只能被某一个 Agent 或某一个人用，无法成为团队共用入口。
问题不在于大家不会写流程，而在于流程没有被收敛成 ​可执行边界​。只写"先做 A，再做 B"远远不够，真正稳定的是输入、输出、失败方式和恢复动作。

Execution Boundary：CLI 不是 API 外壳
很多人第一次做 CLI，会把它理解成"给 HTTP 接口套一层命令行"。这理解太窄了。

在 Agent 场景里，CLI 更像是一道明确的 ​执行边界​。Agent 负责决定什么时候调用、拿什么参数调用；一旦越过这道边界，后面的鉴权、参数检查、分页、网络重试、文件落盘、格式转换、错误归因，就应该交给 CLI 处理。

这样做有个很现实的好处：Agent 不用每次都重新拼一遍请求细节，也不用靠上下文硬记各种接口约束。执行越复杂，这种边界越值钱。
mermaid-01.png

图：Skill 负责编排判断，CLI 负责把执行动作收敛成可复用边界。

上面这张图里最关键的不是"用了 CLI"，而是把职责切干净了。Skill 继续保留灵活性，CLI 则承担确定性。

从脚本阶段到工程阶段：分水岭到底在哪
很多团队最早都会从 Skill + scripts 起步。这完全正常，甚至应该这样做。流程还在试，边界还没收敛，先拿脚本把事情跑起来，成本最低。

但一旦这个能力开始反复被用，继续堆脚本就会很痛苦。脚本路径、环境依赖、输出格式、异常处理方式，全都可能因人而异。最开始觉得灵活，后面就会发现维护者其实在重新猜作者当时怎么想的。

这时候，重点已经不是"还能不能用脚本"，而是执行能力要不要被产品化。

观察维度 Skill + scripts CLI + Skill
适合阶段 早期验证、低频任务、个人提效 团队复用、跨系统接入、高频稳定流程
执行入口 脚本路径和运行约定 稳定命令和明确参数
返回结果 临时日志、散落文件、自定义文本 JSON/JSONL、状态、任务 ID、产物路径
测试方式 依赖脚本作者习惯 可以围绕参数、返回值、错误码做系统测试
风险控制 往往靠人工记忆 可统一做 dry-run、预检、危险操作拦截
维护成本 容易长成脚本堆 初期更重，后期更稳
如果一个能力已经具备下面几个特征，就值得往 CLI 迁移了：
inline-02.png

图：当能力进入高频复用阶段，执行入口需要从脚本约定收敛成稳定 CLI。

步骤相对稳定，不需要每次从零判断。
输入输出可以结构化描述。
失败模式比较固定，能分得清是权限、参数还是外部系统问题。
需要频繁访问外部系统，重复处理很多脏活。
同一件事既希望 Agent 能做，也希望人能直接做。
Skill 的职责，不是替 CLI 干活
Skill 真正有价值的地方，不在于替 CLI 把命令写长一点，而在于它知道什么时候该做、做到哪一步该停、失败后应该怎么改道。

从工程分层上看，我更愿意把它拆成三层：
mermaid-02.png

图：用户意图、Skill 编排层与 CLI 执行层的职责需要严格分层。

这三层的分工可以说得再直白一点：

用户只描述目标，不负责拆命令。
Skill 负责触发判断、上下文读取、前置检查、异常分流和交付规范。
CLI 负责鉴权、参数校验、网络请求、文件处理和结构化输出。
只要这层关系不乱，系统就不容易失控。最怕的是 Skill 里塞满执行细节，CLI 又只做了一个薄薄的命令包装，那最后两边都会变得难维护。

面向 Agent 的 CLI，得先考虑恢复能力
人用命令行时，看到一段报错通常还能自己猜。Agent 不行。它更需要清晰、可解析、能继续往后走的反馈。

所以一个适合 Agent 的 CLI，至少要把这几件事做好：

参数设计：尽量不要让模型猜
能明确成 --doc、–position、–anchor、–format json 的，就别塞进一段自由文本里。自由文本看起来方便，实际最容易把歧义留给后面的执行链路。

输出设计：文本可读只是底线
对 Agent 来说，真正有用的是结构化结果。除了成功与否，还应该有这些字段：

当前状态
阶段名
任务 ID
产物路径或目标链接
出错位置
下一步建议
如果是长任务，最好支持持续查询状态；如果失败了，最好能告诉调用方 “继续监听”“重新鉴权”“修正参数后重试” 到底该走哪条路。

安全设计：危险操作别只靠提示词拦
删除、覆盖、权限变更、批量写入、发布上线这类动作，不能把安全性寄托在"Agent 应该知道不能乱来"上。CLI 里最好就有预检、dry-run、确认机制，必要时强制人工确认。

这不是保守，而是给自动化留刹车。

先把失败路径画出来，成功路径反而简单
很多方案写起来都喜欢从理想流程开始，现实里最伤人的恰恰不是成功路径，而是失败后没人知道该怎么办。

下面这条链路，比较接近真实执行时会遇到的情况：
mermaid-03.png

图：先设计失败分叉与恢复动作，才能让 Agent 在真实链路里稳定续跑。

如果要把这条链路做扎实，Skill 和 CLI 各自都有责任：

CLI 要明确告诉上层失败发生在哪个阶段。
CLI 要给出可恢复动作，而不是只丢一句模糊错误。
Skill 要决定什么时候可以自动重试，什么时候应该停下来问用户。
涉及全量覆盖、批量删除、所有权转移这类动作时，Skill 必须显式设置停止条件。
把失败纳入设计，不是额外工作，而是主干工作。

inline-03.png

图：先设计失败路径和恢复动作，自动化链路才不会在现场失控。

哪些能力适合先做成 CLI
不是所有经验都值得立刻 CLI 化。太早抽象，容易把东西做僵；太晚抽象，又会让脚本债越滚越大。

一般来说，下面这些能力很适合优先收敛成 CLI：

文档创建、更新、素材上传、图表插入
审批读取、任务查询、日志检索
数据查询、报表生成、批处理导出
CI 诊断、构建结果分析、发布前检查
工单流转、状态同步、通知分发
反过来，那些仍处在探索期、严重依赖开放式判断、失败模式还没看清楚的流程，先放在 Skill 里更合适。边界没稳定之前，先别急着过度产品化。

一个更实际的落地顺序
如果团队现在想从零开始做 Skill + CLI，我不建议一上来就搭一个大而全的平台。那样很容易写出一套看上去完整、实际上没人愿意维护的壳。

更稳妥的方式通常是：

先挑一个高频、边界清楚、失败成本可控的场景。
把现有做法整理成 Skill，先明确触发条件、顺序和风险。
找出其中真正稳定重复的部分，把它抽成 CLI。
给 CLI 补上结构化输出、预检、错误阶段和恢复提示。
再让 Skill 去调用 CLI，把上下文读取、异常分流和交付标准补齐。
用真实任务里的失败案例反推参数设计和错误模型，而不是只靠脑补。