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

变成文档并不难难的是让它在第二次、第三次使用时仍然靠谱。原因通常不在知识没写下来而在下面这些地方判断和执行混在一起谁都说不清哪一步可以自动化哪一步必须停下来确认。关键细节散在脚本、接口文档、聊天记录和某个人的习惯里换一台机器就跑不动。一旦失败只能看到一句报错却不知道卡在鉴权、参数、网络还是资源权限。同一套能力只能被某一个 Agent 或某一个人用无法成为团队共用入口。问题不在于大家不会写流程而在于流程没有被收敛成 ​可执行边界​。只写先做 A再做 B远远不够真正稳定的是输入、输出、失败方式和恢复动作。Execution BoundaryCLI 不是 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把上下文读取、异常分流和交付标准补齐。用真实任务里的失败案例反推参数设计和错误模型而不是只靠脑补。