Skills: Version Management & Updates
Last updated: 2026-08-31
A Skill isn't done when written — it evolves. Version management makes evolution traceable, reversible, and coordinated.
1. Semantic Versioning
(1) Version Number Rules
TEXT
📖 Display only
MAJOR.MINOR.PATCH
MAJOR: Incompatible changes (output format change, tool binding change)
MINOR: Compatible additions (new review dimension, new trigger)
PATCH: Compatible fixes (prompt optimization, example update)
(2) Version Change Examples
| Change | Version Upgrade | Reason |
|---|---|---|
| Add security review dimension | 1.0.0 → 1.1.0 | Compatible addition |
| Fix prompt ambiguity | 1.1.0 → 1.1.1 | Compatible fix |
| Change output format to JSON | 1.1.1 → 2.0.0 | Incompatible change |
| Add Git trigger | 2.0.0 → 2.1.0 | Compatible addition |
2. Changelog
(1) CHANGELOG Format
MARKDOWN
# Changelog
## [2.1.0] - 2026-08-20
### Added
- Added Git diff trigger
- Added Mermaid diagram output option
### Changed
- Optimized review prompt, reduced hallucinated output
### Fixed
- Fixed nested code block parsing error
## [2.0.0] - 2026-08-01
### Breaking
- Output format changed from plain text to structured Markdown
- Variable name changed from `file` to `target_file`
### Migration
- Update variable references: `{{file}}` → `{{target_file}}`
- Output parsing needs to adapt to new format (see migration guide)
(2) Migration Guide
Incompatible changes must include a migration guide:
MARKDOWN
## Migration Guide: v1 → v2
### Variable Changes
- `{{file}}` → `{{target_file}}`
- `{{level}}` → `{{severity_level}}`
### Output Format Changes
- v1 plain text → v2 structured Markdown
- Severity markers: `[CRITICAL]` → `🔴`
### Tool Binding Changes
- New dependency: Grep (for context search)
3. Backward Compatibility Strategy
(1) Compatibility Principles
TEXT
📖 Display only
Three Compatibility Principles
├── Output format: New fields don't affect old fields
├── Variable system: New variables have defaults; old variables remain usable
└── Triggers: New triggers don't break existing ones
(2) Deprecation Process
TEXT
📖 Display only
Deprecation Process (spanning 3 versions)
1. v1.1.0: Mark deprecated, still usable, output warning
2. v1.2.0: Disabled by default, requires explicit enable
3. v2.0.0: Completely removed
(3) Compatibility Layer
MARKDOWN
## Compatibility Layer Design
Support both old and new variable names:
{{#if target_file}}
Target file: {{target_file}}
{{#else if file}}
⚠️ Variable `file` is deprecated, please use `target_file`
Target file: {{file}}
{{/if}}
4. Team Sync Updates
(1) Update Strategy
| Strategy | Description | Best For |
|---|---|---|
| Auto-update | PATCH versions applied automatically | Small fixes |
| Notify update | MINOR versions notify users | New features |
| Approval update | MAJOR versions require human confirmation | Incompatible changes |
(2) Sync Process
TEXT
📖 Display only
Team Skill Update Flow
1. Maintainer publishes new version + CHANGELOG
2. Notify team (Slack/email/PR comment)
3. Team members git pull to get updates
4. MAJOR versions require reviewing migration guide
5. Local test verification
6. Confirm and commit project adaptation changes
(3) Version Pinning
YAML
# Project pins Skill versions
skills:
code-review:
version: "^1.5.0"
deploy:
version: "2.0.0"
❓ FAQ
Q Does every change require a version bump?
A Prompt tweaks (like wording improvements) don't need one. Changes affecting output format, variables, or tool bindings do.
Q What if team members haven't updated?
A Add Skill version checks in CI; outdated versions cause build failure with update prompt.
Q How to roll back to an old version?
A
git checkout v1.5.0 -- .claude/skills/code-review.md, or find the old version file from CHANGELOG.📖 Summary
- Semantic versioning: MAJOR incompatible, MINOR additions, PATCH fixes
- Changelog: Added / Changed / Fixed / Breaking + migration guide
- Backward compatibility: New additions don't affect existing; deprecation spans 3 versions; compatibility layers
- Team sync: PATCH auto, MINOR notify, MAJOR approval
📝 Exercises
- Basic (⭐): Add version numbers and CHANGELOG to your created Skills.
- Intermediate (⭐⭐): Design an incompatible upgrade with migration guide and compatibility layer.
- Advanced (⭐⭐⭐): Design a team version sync mechanism with version pinning, auto-checking, and upgrade approval workflows.
