Skills: 版本管理与更新
最后更新：2026-08-31
Skill 不是写完就结束——它会演化。版本管理让演化可追溯、可回退、可协调。
1. 语义化版本
(1) 版本号规则
TEXT
📖 仅展示
MAJOR.MINOR.PATCH
MAJOR：不兼容变更（输出格式改变、工具绑定变化）
MINOR：兼容性新增（新增审查维度、新增触发器）
PATCH：兼容性修复（提示词优化、示例更新）
(2) 版本变更示例
| 变更 | 版本升级 | 原因 |
|---|---|---|
| 新增安全审查维度 | 1.0.0 → 1.1.0 | 兼容性新增 |
| 修复提示词歧义 | 1.1.0 → 1.1.1 | 兼容性修复 |
| 改变输出格式为 JSON | 1.1.1 → 2.0.0 | 不兼容变更 |
| 新增 Git 触发器 | 2.0.0 → 2.1.0 | 兼容性新增 |
2. 变更日志
(1) CHANGELOG 格式
MARKDOWN
# Changelog
## [2.1.0] - 2026-08-20
### Added
- 新增 Git diff 触发器
- 新增 Mermaid 图表输出选项
### Changed
- 优化审查提示词，减少幻觉输出
### Fixed
- 修复嵌套代码块解析错误
## [2.0.0] - 2026-08-01
### Breaking
- 输出格式从纯文本改为 Markdown 结构化
- 变量名从 `file` 改为 `target_file`
### Migration
- 更新变量引用：`{{file}}` → `{{target_file}}`
- 输出解析需适配新格式（见迁移指南）
(2) 迁移指南
不兼容变更必须附带迁移指南：
MARKDOWN
## 迁移指南：v1 → v2
### 变量变更
- `{{file}}` → `{{target_file}}`
- `{{level}}` → `{{severity_level}}`
### 输出格式变更
- v1 纯文本 → v2 Markdown 结构化
- 严重程度标记：`[CRITICAL]` → `🔴`
### 工具绑定变更
- 新增依赖：Grep（用于上下文搜索）
3. 向后兼容策略
(1) 兼容性原则
TEXT
📖 仅展示
兼容性三原则
├── 输出格式：新增字段不影响旧字段
├── 变量系统：新变量有默认值，旧变量保持可用
└── 触发器：新增触发器不破坏已有触发
(2) 废弃流程
TEXT
📖 仅展示
废弃流程（跨越 3 个版本）
1. v1.1.0：标记废弃，但仍可用，输出警告
2. v1.2.0：默认禁用，需显式启用
3. v2.0.0：完全移除
(3) 兼容层
MARKDOWN
## 兼容层设计
支持新旧两种变量名：
{{#if target_file}}
目标文件：{{target_file}}
{{#else if file}}
⚠️ 变量 `file` 已废弃，请使用 `target_file`
目标文件：{{file}}
{{/if}}
4. 团队同步更新
(1) 更新策略
| 策略 | 说明 | 适合 |
|---|---|---|
| 自动更新 | PATCH 版本自动应用 | 小修复 |
| 通知更新 | MINOR 版本通知用户 | 新功能 |
| 审批更新 | MAJOR 版本需人工确认 | 不兼容变更 |
(2) 同步流程
TEXT
📖 仅展示
团队 Skill 更新流程
1. 维护者发布新版本 + CHANGELOG
2. 通知团队（Slack/邮件/PR 评论）
3. 团队成员 git pull 获取更新
4. MAJOR 版本需审查迁移指南
5. 本地测试验证
6. 确认后提交项目适配改动
(3) 版本锁定
YAML
# 项目锁定 Skill 版本
skills:
code-review:
version: "^1.5.0"
deploy:
version: "2.0.0"
❓ 常见问题
Q 每次改动都要升级版本号吗？
A 提示词微调（如措辞优化）不需要。影响输出格式、变量或工具绑定的改动需要。
Q 团队有人没更新怎么办？
A CI 中检查 Skill 版本，版本过低时构建失败并提示更新。
Q 如何回退到旧版本？
A
git checkout v1.5.0 -- .claude/skills/code-review.md，或从 CHANGELOG 找到旧版本文件。📖 小节
- 语义化版本：MAJOR 不兼容、MINOR 新增、PATCH 修复
- 变更日志：Added / Changed / Fixed / Breaking + 迁移指南
- 向后兼容：新增不影响旧有、废弃跨 3 版本、兼容层
- 团队同步：PATCH 自动、MINOR 通知、MAJOR 审批
📝 作业
- 基础题（难度⭐）：为你创建的 Skill 添加版本号和 CHANGELOG。
- 进阶题（难度⭐⭐）：设计一次不兼容升级，包含迁移指南和兼容层。
- 挑战题（难度⭐⭐⭐）：设计团队版本同步机制，含版本锁定、自动检查和升级审批流程。
