起因：同一个流程，每次都靠记忆
我们的一个后端服务项目，版本发布是一套多阶段流程：基线校验、推送分支、等待 CI、改 CHANGELOG、合并主干、打 tag、部署、冒烟。这套流程分散在文档、脚本注释和个人经验里，每次发布都由 AI Agent 执行——而 Agent 经常给出错误的顺序。
错误的典型是：在内容还没冻结时就改 CHANGELOG 标题、改完标题又重复跑一遍 CI、把空段落插到错误位置。这些错误不造成代码损失，但每次都暴露「流程只存在于人脑，没有固化下来」的问题。
解决方案不是再写一份文档，而是把它做成 Agent 能自动加载的 skill。
第一步：先有权威 SOP，再有 skill
我们把发布流程写成一份完整的 SOP（标准操作流程），包含每个阶段的命令、检查点、判定标准。原则很简单：
权威说明只保留一处，其他位置都是引用。
之前发布流程的信息散落在三处（项目说明文档、发布脚本注释、运维手册），内容还不一致。收敛后：
- 一份权威 SOP 文档，是唯一操作手册
- 其他文档（脚本注释、项目说明、运维手册）全部改为引用它
- skill 作为速查指引，指向 SOP 而不是重复内容
这样改一处，全链路生效，不会出现「文档改了三处漏两处」。
第二步：让发布流程承认自己的边界
写 SOP 时我们明确了一个关键定位：
发布是纯流程化执行，不包含代码逻辑/内容确认。
代码的完整性和正确性在开发与产品决策阶段已经确认。发布只做流程性检查：preflight 通过、CI 绿、工作区干净、tag 唯一、主干同步。发布流程里不应该出现「审阅代码」这种步骤——那相当于产品已经决定上线了，你还说要再评审一遍功能，逻辑上是错位的。
这个定位决定了 SOP 的骨架：每个阶段都是「命令 + 检查点」，不含任何代码质量判断。
第三步：手动演练，用真实发布验证 skill
skill 写好不等于能用。我们决定下一次发布走手动流程，同时把每一步记录下来，作为 skill 的实践依据——这相当于用真实环境给 skill 做端到端测试。
演练过程中踩到了六个真实的坑，每个都回填进了 skill：
坑 1：dry-run 跑太早，必死
发布预览命令（release --dry-run）在改 CHANGELOG 标题前跑，会在「缺少版本段落」检查处直接退出——因为段落还没建，根本走不到后续校验。这个命令的正确时机是改题之后、合并主干之后，此时段落存在、主干已同步，才能完整校验。
教训：先读透工具的前置检查顺序，再决定调用时机。
坑 2：改题后重复跑 CI
改 CHANGELOG 标题是纯文本提交，代码没变。但流程初版要求改完标题再 push 到开发分支等 CI——这是纯浪费（配额有限，CI 每次跑都是成本）。
正确路径：纯文本提交直接随合并主干时一起走，主干的 CI（含镜像构建）就是发布验证。
坑 3：空段落插错位置
改 CHANGELOG 时要在文件顶部新建空「未发布」段，供下一版本累积。第一版把它插到了版本段后面，用户一眼看出结构错误——正确的参照是上一个版本的改题提交。
教训：文档有历史结构惯例时，先看历史提交怎么做的，别凭想当然。
坑 4：CI 输出误判
gh run watch 输出的 X Process completed with exit code 1（lint job）和某个 artifact 下载失败提示，看起来像 CI 挂了。实际那些是 warn 级别的 annotations（Node 版本弃用提醒、辅助步骤失败），不是 job 失败。权威判定要用 gh run view --json conclusion。
教训：不要目视终端输出判断 CI 状态，用结构化 API 查询。
坑 5：共享终端被污染
发布全程在 tmux 共享终端执行以便审计。但共享终端是通用会话，可能被其他 Agent 并发使用，历史不干净。后来改为发布专属会话，阶段 0 创建、前置销毁重建、每次从零开始、发布后销毁——保证审计历史干净。
坑 6：外部依赖中断
发布进行到一半，CI 因为平台免费额度耗尽而失败（非代码问题）。此时 tag 已推送，重新执行发布会死于「tag 已存在」检查。恢复路径是：补跑该 tag 的 CI + 手动补建 Release 页（先确认不存在避免重复创建）。
教训：外部基础设施中断不是代码问题，不要改代码；要设计恢复路径。
第四步：基线校验作为强制前置门
用户补充了一个重要规则：任何发布步骤之前，先验证自上个版本以来的所有提交——
- 单链（无 merge 提交）
- 开发分支可 fast-forward 合并到主干
- 提交时间线性（无乱序）
- 签名完整（全部通过 GPG 验证）
任何一项不符，立刻报告并终止发版。这相当于发布前的「体检」，确保要发布的内容是可审计、可追溯、可回滚的。
设计：执行模式与安全护栏
发布是高风险的，skill 设计了明确的执行模式：
- 自动模式：命令行工具可用时，CI 全程自动阻塞监控，轮询间隔设为 15 秒（默认 3 秒太频繁，浪费配额）
- 协作模式：命令行工具不可用时，Agent 不阻塞、不轮询，停在「等待开发者确认」点，由开发者告知结果后继续
- 会话前台确认：每次向发布会话发命令前，确认会话存在且在前台——共享终端可能被用户关闭，向已关闭的会话发命令会静默丢失
结尾
一次发布演练，把分散的记忆固化成了一套可复用的流程资产。核心收获是：
- 权威内容只留一处，其他全部引用
- 发布是流程执行，不含代码评审
- Skill 必须经过真实演练验证，踩坑后回填
- 基线校验前置，不合规就终止
- 高风险操作要有执行模式和安全护栏
这套方法论不只适用于发布——任何「多阶段 + 高风险 + 需要 Agent 重复执行」的流程，都值得这样做。