Skills 版本管理与迭代

Skill 随着需求变化而不断演进。合理的版本管理，能让你在修改时不丢失已有成果，也能在出错时快速回退。

版本号的约定

Skills 采用语义化版本号（Semantic Versioning），格式为 MAJOR.MINOR.PATCH。

版本号段	何时递增	示例
MAJOR（主版本）	不兼容的重大改动（如输入格式改变）	1.0.0 → 2.0.0
MINOR（次版本）	新增功能，但向下兼容	1.0.0 → 1.1.0
PATCH（修订版）	Bug 修复，不影响功能	1.0.0 → 1.0.1

在 SKILL.md 中声明版本

实例

---
name: csv-analyzer
version: 1.2.0
description: 分析 CSV 文件，输出统计摘要。
---

使用 Git 管理 Skill 版本

Git 是管理 Skill 版本的最佳工具，每次修改都可以形成一条清晰的历史记录。

实例

# 初始化 Git 仓库
cd my-skill/
git init
git add .
git commit -m "feat: 初始版本 v1.0.0"

# 修改 Skill 后提交新版本
git add SKILL.md
git commit -m "fix: 修复文件路径处理的空格问题"

# 为稳定版本打标签
git tag v1.0.1
git tag v1.1.0 -m "新增多文件批量处理功能"

前缀	含义	示例
feat:	新功能	feat: 新增 Excel 输出支持
fix:	Bug 修复	fix: 修复空文件时的崩溃问题
docs:	文档更新	docs: 补充参数说明
refactor:	代码重构（无功能变化）	refactor: 将清洗逻辑抽取为独立函数
perf:	性能优化	perf: 大文件处理速度提升 3 倍

在 SKILL.md 中维护 CHANGELOG

对于会被他人使用的 Skill，在 SKILL.md 末尾附上变更记录，能帮助用户了解每个版本的改动。

## 版本历史

### v1.2.0（2026-05-18）
- 新增：支持 .xlsx 输入格式
- 优化：大文件（>10MB）处理速度提升 40%

### v1.1.0（2026-04-10）
- 新增：--col 参数，支持只分析指定列
- 修复：列名包含空格时的解析错误

### v1.0.0（2026-03-01）
- 初始版本：支持 CSV 文件的基础统计分析

版本迁移：不兼容变更的处理方式

当 Skill 发生不兼容变更（如修改了输入格式、删除了某项功能），需要给现有用户明确的迁移指引。

## 迁移指南：从 v1.x 升级到 v2.0

### 主要变化

v2.0 修改了输出文件的命名规则，由原来的 `output.xlsx` 改为带日期的 `output_YYYYMMDD.xlsx`。

### 受影响场景

如果你的工作流依赖固定的输出文件名，需要在使用时重命名文件，或使用 `--output` 参数指定文件名。

### 迁移步骤

1. 更新 Skill 到 v2.0
2. 检查是否有依赖固定文件名的脚本或工作流
3. 如有，添加 `--output output.xlsx` 参数保持旧行为

不兼容变更应该在发布前充分评估影响范围。如果使用者众多，可以考虑保留旧参数并标记为"已废弃"，给用户过渡时间，而不是直接删除。

回退到历史版本

实例

# 查看所有历史提交
git log --oneline

# 查看所有版本标签
git tag

# 回退到指定版本标签
git checkout v1.1.0

# 或回退到指定提交（通过 commit hash）
git checkout a3f7b2c

# 若需要将回退版本作为新分支继续开发
git checkout -b hotfix/v1.1.1 v1.1.0

返回顶部

菜鸟教程