Skill 版本管理与变更日志：让升级不踩坑

为什么要版本管理

Skill 不是写完就完的。它会迭代、修复、重构。没有版本管理：

• 用户不知道该不该升级
• 升级后出问题不知道改了什么
• 团队协作时互相覆盖

语义化版本号

格式：MAJOR.MINOR.PATCH

• MAJOR：不兼容的 API 变更（升级需注意）
• MINOR：向后兼容的新功能
• PATCH：向后兼容的 Bug 修复

SKILL.md 中声明版本

---
name: my-skill
version: 2.1.0
minOpenClawVersion: 1.5.0
---

# My Skill

## 变更日志

### v2.1.0 (2026-04-24)
- 新增：支持批量操作
- 修复：超时处理逻辑

### v2.0.0 (2026-04-10)
- 破坏性变更：输出格式从 text 改为 json
- 新增：错误重试机制

变更日志规范

每条记录包含：

1. 新增（Added）：新功能
2. 变更（Changed）：行为变化
3. 修复（Fixed）：Bug 修复
4. 废弃（Deprecated）：即将移除的功能
5. 移除（Removed）：已删除的功能

升级指南

对于 MAJOR 版本升级，提供迁移指南：

## 从 v1.x 升级到 v2.x

1. 输出解析改为 JSON：替换 text 解析逻辑
2. 配置格式变更：参见新 SKILL.md
3. 废弃的参数：remove --verbose 改用 --log-level

Git 标签

git tag -a v2.1.0 -m "新增批量操作"
git push origin v2.1.0

这样每个版本都有明确锚点，可随时回退。