Skill SemVer
Automatic version control for Claude Code Skills with semantic versioning, auto-backup, and changelog generation.
Features
- 🔄 Auto-backup: Automatically backs up SKILL.md on every edit
- 📋 Semantic Versioning: MAJOR.MINOR.PATCH format with pre-release support
- 📜 Changelog: Track changes with Keep a Changelog format
- 🎯 Zero config: Works out of the box with PostToolUse hook
- 📁 Organized: Clean releases/ folder for version history
- 📅 Auto-update: Automatically updates "Last Updated" date
- 🏷️ Pre-release: Support for alpha, beta, rc versions (e.g.,
1.0.0-alpha,2.0.0-beta.1)
Quick Start
1. Install the plugin
# Using Claude Code CLI
claude mcp add-json skill-semver '{"type":"stdio","command":"npx","args":["-y","skill-semver"]}'
2. Or clone locally
# Clone this repo
git clone https://github.com/cathy-kim/skill-semver.git
# Install dependencies
cd skill-semver
npm install
3. Add version header to your SKILL.md
# My Skill
> Description of the skill
**Version**: 1.0.0
**Last Updated**: 2026-01-30
4. Edit and save - backup is automatic!
The hook will create releases/v1.0.0_2026-01-30_SKILL.md automatically.
Plugin Structure
skill-semver/
├── .claude-plugin/
│ └── plugin.json # Plugin metadata
├── skills/
│ └── versioning-guide/
│ └── SKILL.md # Versioning guide skill
├── hooks/
│ ├── hooks.json # Hook configuration
│ └── skill-version-hook.ts # Auto-backup hook
├── scripts/
│ └── migrate-skill-versioning.ts # Migration script
├── examples/
│ └── example-skill/ # Example skill structure
├── package.json
├── CHANGELOG.md
├── RESEARCH-SUMMARY.md
└── README.md
Skill Folder Structure
After using this plugin, your skills will have this structure:
.claude/skills/your-skill/
├── SKILL.md # Current version
├── CHANGELOG.md # Change history
└── releases/ # Version snapshots
├── v1.0.0_2025-12-01_SKILL.md
├── v2.0.0-beta.1_2025-12-15_SKILL.md
└── v3.0.0_2026-01-15_SKILL.md
Version Formats
Supported Versions
| Format | Example | Description |
|---|---|---|
| Standard | 1.2.3 | MAJOR.MINOR.PATCH |
| Pre-release | 1.0.0-alpha | Alpha version |
| Pre-release with number | 2.0.0-beta.1 | Beta version 1 |
| Release candidate | 3.0.0-rc.1 | Release candidate |
| Build metadata | 1.0.0+build.123 | With build info |
Version Bump Guide
| Change Type | Version | Example |
|---|---|---|
| Breaking change | MAJOR | Workflow restructure |
| New feature | MINOR | Add new agent |
| Bug fix | PATCH | Fix typo |
Initial Development (0.x.x)
Versions starting with 0. are marked as "Initial Development" and indicate the skill is not yet stable.
How It Works
- PostToolUse Hook detects when you edit a SKILL.md file
- Version Extraction reads the
**Version**: X.X.Xheader - Last Updated automatically updates the date
- Auto-backup creates
releases/v{VERSION}_{DATE}_SKILL.md - CHANGELOG updates with new version entry
- Skip duplicates - won't create backup if same version exists
Version Header Formats
The hook recognizes these version patterns:
**Version**: 1.0.0 ✓ Preferred
**Version**: 1.0.0-alpha ✓ Pre-release
Version: 1.0.0 ✓ Alternative
# My Skill v1.0.0 ✓ In title
Migration
For existing skills without versioning:
# Run from your project root
npx tsx scripts/migrate-skill-versioning.ts
The migration script will:
- Create
releases/folders - Add version headers to SKILL.md files
- Generate CHANGELOG.md from git history
- Migrate existing backup files
CHANGELOG Format
# Changelog - my-skill
## [1.1.0] - 2026-01-30
### Added
- New feature description
### Changed
- Updated behavior
### Fixed
- Bug fix description
What's New in v1.1.0
- Pre-release Support: Handle alpha, beta, rc versions
- Build Metadata: Support
+build.123suffixes - Auto Last Updated: Automatically update the date field
- Performance: Reduced file reads from 2 to 1
- Cross-platform: Fixed path separator issues (Windows/Mac)
Requirements
- Claude Code CLI v1.0.33+
- Node.js 18+
- TypeScript (tsx)
License
MIT
Author
Made with ❤️ for the Claude Code community