LESSON 10 / 2026.11.06
Lesson Objective: You will be able to 版本号、变更日志、兼容矩阵与回滚条件 写进 Skill 仓库的 reference/release-checklist.md,而不是在聊天里说「今晚再发」。上一课你已经写过 computer-use 坐标契约与 Harness 边界:https://school.myshirtai.com/?p=4478。本课在契约之上,处理发布治理——谁改了什么、能不能合、坏了怎么退。形态为课程学习(文档+练习);未本机跑 CI / Skills API 上传,故不写第一人称跑通数字。
仓库里缺发布清单,线上就会默认
latest:谁都能覆盖你生产 Agent 正在用的 Skill。
前置与可验证目标
请先完成第 9 课《把 computer-use 坐标契约与 Harness 边界写进 Skill》:https://school.myshirtai.com/?p=4478。手头至少要有:可加载的目标 Skill、reference/ 写权限或能提 PR、第 6 课评测钩子(失败样例能挂进回归)。更早基础可回补:第 1 课 https://school.myshirtai.com/archives/3378; Lesson 2 https://school.myshirtai.com/archives/3462; Lesson 3 https://school.myshirtai.com/archives/3521; Lesson 4 https://school.myshirtai.com/archives/3661; Lesson 5 https://school.myshirtai.com/?p=3948; Lesson 6 https://school.myshirtai.com/?p=4048; Lesson 7 https://school.myshirtai.com/?p=4191;第 8 课 https://school.myshirtai.com/?p=4331The
今晚九十分钟只给One Skill 加发布清单,不要顺便重构全部脚本。
- 目标 A:提交
reference/release-checklist.md(含版本、变更、兼容、回滚四块)。 - 目标 B:挂两条失败样例——漏版本字段、漏回滚条件——并能被第 6 课评测钩子点名。
- 目标 C:在清单里写明「生产引用是否钉死 version id / 禁止默默追 latest」。未实测 API 上传时,标注「未本机跑 CI」即可。
概念:发布清单要钉死什么
第 9 课保证点坐标不错。第 10 课补的是:Skill 一旦进共享目录或 Skills API,缺版本与回滚就会变成「谁最后上传谁说了算」。公开材料里,Agent Skills 是带 SKILL.md 的文件夹;API 侧创建版本时,后续上传必须保持同一 immutable name,版本用独立 id 寻址,也可用字面量 latest——这正是生产要显式决策的点。
清单不是再写一篇 README 感想,而是发布前的门禁表。建议至少钉四件事:
- 版本:仓库标签 /
SKILL.md内版本字段 / API version id,三者如何对齐。 - 变更日志:本次改了 description、脚本还是契约;影响哪些触发句。
- 兼容:依赖的 Claude Code / API / Harness / 坐标契约版本;与第 9 课 computer-use 声明是否冲突。
- 回滚:失败信号是什么、回退到哪一个 version id 或 git tag、谁有权限执行。

练习:写出可粘贴的发布清单
在目标 Skill 下新建 reference/release-checklist.md。下面模板可直接粘贴后改尖括号字段;代码块仅作文档练习,未本机跑 CI。
# Release checklist — <skill-name>
## Version
- git tag:
- SKILL.md version field:
- API skill_id / version id (if uploaded):
- production pin: version id | latest (default: pin id)
## Changelog
- triggers / description:
- scripts / reference:
- breaking? yes/no — migration:
## Compatibility
- Claude Code / API surface:
- Harness / computer-use contract (lesson 9):
- eval suite id (lesson 6):
## Rollback
- fail signals:
- rollback to:
- owner / timebox:
- stop if:
材料清单:写权限或 PR;能把第 6 课评测集加两条「发布门禁」用例;能在 PR 描述里贴清单勾选结果。没有真实线上事故,就用合成样例:description 改了却未升版本、生产仍追 latestThe

- 复制模板进
reference/release-checklist.md,填本 Skill 真字段。 - 把「生产 pin」默认写成具体 version id 或 git tag,禁止只写 latest。
- 在第 6 课评测目录加两条失败样例(见下一节)。
- PR 正文贴清单勾选;评审只盯四块是否空。
失败样例与第 6 课评测钩子
评测不是可选项。第 6 课已教过用评测集做回归;本课要求发布门禁也能被同一钩子点名。至少准备两条应失败样例:
| 样例 | 缺什么 | 期望评测结果 |
|---|---|---|
| 漏版本 | 无 git tag / 无 version 字段 / 无 pin | 门禁红灯,禁止合入 |
| 漏回滚 | 有变更日志但无 fail signals / rollback to | 门禁红灯,禁止合入 |
| 兼容空白 | 改了 computer-use 却未引用第 9 课契约 | 警告或红灯(团队自定) |

把样例文件名写进清单的「eval suite id」一行,例如 evals/release-missing-version.md。这样第 6 课钩子与第 10 课门禁共用同一套路径约定,避免两套目录漂移。
Note:本文未本机调用 Skills API 创建版本,也未跑仓库 CI。练习验收标准是「清单文件 + 两条失败样例 + PR 勾选」齐备;不要把文档练习写成「已上传生产」。
Preview of the Next Lesson
下一课预告(待定):生产灰度与 MCP 白名单——如何把已钉死的 version id 放进灰度流量、如何给高风险工具调用加白名单与观察期。本课先把离线发布清单与评测红灯跑稳;没有回滚条件,灰度只会放大事故面。
Table of Contents for This Series
- Lesson 1: Write Your First Claude Agent Skill That Triggers Automatically in 30 Minutes — https://school.myshirtai.com/archives/3378
- Lesson 2: Adding a Reference to Skill / Validation Loop for “Write the Plan First, Then Execute” — https://school.myshirtai.com/archives/3462
- Lesson 3: Scripted Skills and Security Audits — https://school.myshirtai.com/archives/3521
- Lesson 4: Iterating Using Real-World Failure Cases description — https://school.myshirtai.com/archives/3661
- Lesson 5: Integrating Skill with a Real Repository's CI / Team-Shared Directory — https://school.myshirtai.com/?p=3948
- Lesson 6: Performing Regression on a Skill Using a Validation Set — https://school.myshirtai.com/?p=4048
- Lesson 7: Multi-Skill Choreography: Decomposing and Recombining Boundaries and Arbitrating Trigger Conflicts — https://school.myshirtai.com/?p=4191
- Lesson 8: Implementing the Task/Subagent Pattern in a Skill: Parallelism Boundaries and Context Isolation — https://school.myshirtai.com/?p=4331
- 第 9 课:把 computer-use 坐标契约与 Harness 边界写进 Skill — https://school.myshirtai.com/?p=4478
- 第 10 课:把 Skill 发布清单写进仓库:版本、变更日志、兼容与回滚(本文)
Our assessment:发布清单的价值不在「又多一个 Markdown」,而在强迫你在合入前回答版本、兼容与回滚。钉死 version id、挂上第 6 课失败样例,比口头「小心 latest」更可验收。
Reference Links
- Claude Code Docs:Extend Claude with skills
- Agent Skills Overview(开放标准)
- GitHub: anthropics/skills
- Claude API Docs:Skill Versions
- 第 9 课:computer-use 坐标契约与 Harness
- 第 6 课:用评测集给 Skill 做回归


Comment List (0):
Load More Comments Loading...