Skills Version Management and Iteration

Skills evolve as requirements change. Proper version management allows you to preserve existing work when making changes and quickly roll back when errors occur.

Version Number Conventions

Skills use Semantic Versioning, with the format:MAJOR.MINOR.PATCH。

Version segment When to increment Example
MAJOR Incompatible major changes (e.g., input format changes) 1.0.0 → 2.0.0
MINOR New features, but backward compatible 1.0.0 → 1.1.0
PATCH Bug fixes, no functional impact 1.0.0 → 1.0.1

Declaring the Version in SKILL.md

Example

---
name: csv-analyzer
version: 1.2.0
description: Analyzes CSV files and outputs a statistical summary.
---

Managing Skill Versions with Git

Git is the best tool for managing Skill versions; every change produces a clear history record.

Example

# Initialize Git repository
cd my-skill/
git init
git add .
git commit -m "feat: initial version v1.0.0"

# Commit a new version after modifying the Skill
git add SKILL.md
git commit -m "fix: fix the space issue in file path processing"

# Tag a stable version
git tag v1.0.1
git tag v1.1.0 -m "Add multi-file batch processing functionality"

Recommended Commit Message Format

Prefix Meaning Example
feat: New feature feat: add Excel output support
fix: Bug fix fix: fix crash on empty files
docs: Documentation update docs: add parameter descriptions
refactor: Code refactoring (no functional change) refactor: extract cleaning logic into a separate function
perf: Performance optimization perf: 3x speedup for large file processing

Maintaining a CHANGELOG in SKILL.md

For Skills that will be used by others, attaching a change log at the end of SKILL.md helps users understand the changes in each version.

## 版本历史

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

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

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

Version Migration: Handling Breaking Changes

When a Skill undergoes breaking changes (e.g., input format changes or feature removal), you need to provide clear migration guidance to existing users.

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

### 主要变化

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

### 受影响场景

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

### 迁移步骤

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

Breaking changes should be fully assessed for impact before release. If many users are affected, consider keeping the old parameter and marking it as "deprecated" to give users a transition period, rather than deleting it outright.

Rolling Back to a Previous Version

Example

# View all historical commits
git log --oneline

# View all version tags
git tag

# Roll back to the specified version tag
git checkout v1.1.0

# Or roll back to a specific commit (via commit hash)
git checkout a3f7b2c

# If you need to continue development from the rolled-back version as a new branch
git checkout -b hotfix/v1.1.1 v1.1.0
Other Extensions