SKILL.md
Releasing a New Version
Overview
Bump versions, tag, and publish a GitHub Release with an auto-generated changelog. All version sources must stay in sync.
Version Sources (must match)
| File | Field |
|---|---|
.claude-plugin/plugin.json |
version |
.claude-plugin/marketplace.json |
plugins[0].version |
| Git tag | vX.Y.Z |
Steps
1. Determine version bump
Check commits since last tag:
git log $(git describe --tags --abbrev=0)..HEAD --onelineApply semver: patch for fixes, minor for features, major for breaking changes.
2. Generate changelog
Group commits by type when there are enough to justify it:
- Features (
feat:) - Fixes (
fix:) - Refactors (
refactor:) - Other (everything else)
For small releases (< 5 commits), a flat list is fine.
3. Confirm before publishing
The script pushes to origin and creates a public GitHub Release — irreversible. First show the user the final version number and the full changelog text, and get explicit approval before running it. Do not invoke the script autonomously.
4. Execute release
After approval, run the release script:
${CLAUDE_PLUGIN_ROOT}/scripts/release.sh "<version>" "<changelog>"This handles all mechanical steps: update both JSONs → commit → tag → push → create GitHub Release.
Recovery
| Condition | Handling |
|---|---|
git describe fails (no prior tag) |
First release — pick an initial version (e.g. 0.1.0); changelog from full git log --oneline |
gh not authenticated |
Stop; ask the user to run gh auth login before retrying |
| Script fails mid-run | Inspect what completed (git tag, gh release list); finish remaining steps manually, don't re-run the whole script |
Common Mistakes
| Mistake | Fix |
|---|---|
| marketplace.json version not updated | Always update both JSON files together |
| Tag created before commit pushed | Push commit first, then tag, or use --tags |
| Changelog missing commits | Use prevtag..HEAD, not prevtag..new_tag before tagging |