普通代码升级，大家会看 API 有没有变。Skill 升级更麻烦：接口可能没变，但行为已经变了。
比如一个代码审查 Skill，输入还是“变更文件列表”，输出还是“审查意见”。但你改了提示词，让它从“只报严重问题”变成“所有建议都列出来”。接口没变，下游体验却完全不同。
这就是 Skill 版本控制最容易踩坑的地方：看起来只是小改动，实际已经改变了使用者的预期。
本文要点
- Skill 的版本号要看接口，也要看行为。
- 提示词、规则、知识库、输出格式变化，都可能是版本变化。
- 高风险升级必须灰度和可回滚。
- 升级说明要写“谁会受影响”，不要只写“优化了效果”。
为什么 Skill 升级更难
Skill 通常不只是代码，它还包括提示词、流程、示例、规则、知识库和输出格式。
这些东西的变化不一定能被类型系统发现。
比如：
- 提示词从“简洁回答”改成“详细解释”，调用方可能嫌输出太长。
- 输出字段名没变，但严重程度判断标准变了，报表统计会失真。
- 知识库更新后，回答依据变了，老用户会觉得前后不一致。
- 新增安全检查后，原来通过的任务开始失败。
所以 Skill 版本控制不能只问“代码有没有破坏 API”，还要问“使用者感受到的行为有没有变”。
版本号怎么判断
可以继续使用 MAJOR.MINOR.PATCH，但判断标准要扩展。
PATCH 适合小修小补。比如修错别字、修明显 bug、补充不会影响行为的文档。
MINOR 适合向后兼容的增强。比如新增一个可选字段、新增一个检查项但默认关闭、补充更多示例但不改变输出格式。
MAJOR 适合不兼容变化。比如输出结构变了、默认策略变了、原有字段删除了、提示词导致行为明显不同、调用方需要改适配逻辑。
一个简单判断是：
使用者不改任何东西，还能得到预期结果吗？
能，只是更稳定：PATCH
能，但多了可选能力：MINOR
不能，需要重新适配：MAJOR兼容性看什么
Skill 的兼容性要看四层。
第一层是输入兼容。旧输入还能不能跑？字段缺失时有没有默认值？旧配置还能不能读取？
第二层是输出兼容。下游依赖的字段还在不在？类型有没有变？严重程度、状态码、错误码有没有重新定义？
第三层是行为兼容。同样的输入，输出风格、判断标准、风险等级是否明显变化？
第四层是性能兼容。升级后是否变慢、变贵、调用次数变多？一个 Skill 从 3 秒变成 20 秒，即使输出更好，也可能破坏调用方流程。
建议每个重要 Skill 准备一组回归用例。升级前后跑同一批输入，看输出结构、关键判断和耗时是否在可接受范围内。
怎么发布更稳
Skill 升级不要一把梭。
更稳的方式是三步。
第一，影子运行。新版本先用真实输入跑一遍，但不影响真实结果。比较新旧版本差异，看看有没有意外变化。
第二，小流量灰度。先给少量任务或内部用户使用，观察错误率、人工回退率和用户修正次数。
第三，可回滚发布。保留旧版本，发现问题可以快速切回。不要只保留一份最新 Skill 文件。
高风险 Skill 还要支持双版本共存。比如 code-review@1 和 code-review@2 同时存在，让不同项目按自己的节奏迁移。
升级说明怎么写
很多升级说明只写“优化提示词，提升效果”。这句话几乎没用。
好的升级说明应该写清楚四件事：
- 改了什么：提示词、规则、输出格式、知识库还是配置。
- 谁受影响：调用方、最终用户、报表系统、测试用例。
- 需要做什么：是否要改字段、重跑测试、更新文档。
- 如何回滚：旧版本在哪里，回滚命令或流程是什么。
示例：
code-review-skill 2.0.0
变化：
- 默认开启安全扫描规则。
- 输出字段 severity 从中文改为 enum: low | medium | high | critical。
影响：
- 依赖中文严重程度的报表需要适配。
- 老项目可能出现更多 high 级别问题。
迁移：
- 更新报表字段映射。
- 先在测试仓库灰度 3 天。
回滚：
- 可切回 code-review-skill 1.8.4。结论
Skill 升级最怕“悄悄变味”：接口没变，行为却变了；说明写着优化，使用者却要重做适配。
版本号不是形式，它是在提醒别人风险。只要输出、判断标准、默认行为或性能明显变化，就要认真对待版本升级。越重要的 Skill，越要灰度、回归和可回滚。