| name | bump-version |
| description | Increment semantic version numbers using controlled preview-then-apply workflow to update plugin metadata safely. Use when (1) after completing a set of changes that need version increment before release, (2) when preparing to sync versions across metadata files using sync-versions, (3) before creating a release tag or publishing to the marketplace, (4) when explicitly requested with a specific bump type, (5) after merging a pull request that requires version increment according to changelog, (6) when planning release schedules and need to calculate what the next version would be. |
Bump Version
Version numbers communicate the magnitude and nature of change through semantic arithmetic—major increments signal breaking changes, minor increments announce new capabilities, patch increments mark refinements. This skill handles the mechanics of that arithmetic while maintaining safety through preview-then-apply workflow that lets you verify the calculation before committing to metadata.
Instructions
-
Translate changes into semantic version language. Breaking changes that alter existing behavior map to major bumps, new features that extend functionality without breaking compatibility map to minor bumps, and bug fixes or internal improvements map to patch bumps. The version increment shapes how users understand what changed, so judge impact from their perspective—whether they'll need to adapt their usage—rather than counting lines modified.
-
Preview the calculation before applying. Execute the script without --apply to see what the new version would be, confirming the bump logic produces the expected result before the change propagates to metadata files that other tools depend on. This dry-run workflow catches misalignment between your intent and the arithmetic outcome while changes remain reversible through simple re-execution.
-
Verify the version fits the narrative. Compare the calculated version against recent changelog entries to confirm it aligns with the magnitude of changes since the last release, check that it follows sequentially without skipping numbers, and ensure it continues the story the version history tells about the plugin's evolution. A version that seems wrong in context usually signals either miscategorized changes or a bump type mismatch.
-
Apply atomically and confirm synchronization. When the preview matches your intent, run with --apply to update the plugin's plugin.json file through atomic write that validates format, reads current version, calculates increment, and updates metadata as a single operation. Follow by running check-versions to confirm both plugin.json and marketplace.json show the same version, since release tooling expects that consistency.
-
Align changelog with version semantics. Update the corresponding CHANGELOG.md entry to match the new version, ensuring the documented changes justify the bump level you selected—patch entries should describe fixes, minor entries should highlight new features, major entries should explain breaking changes. The changelog and version tell the same story from different angles; when they diverge, users lose the ability to predict impact from version numbers alone.
Script Usage
.claude/scripts/bump-version.sh --version 1.2.3 --bump patch
.claude/scripts/bump-version.sh --plugin thinkies --bump minor
.claude/scripts/bump-version.sh --plugin thinkies --bump minor --apply
The script validates semantic version format (X.Y.Z), supports three bump types (major, minor, patch), and operates on either explicit version strings or plugin metadata files.
Examples
Example 1: Patch bump for bug fixes
After fixing several bugs in the thinkies plugin, I need to increment the version to mark the release:
$ .claude/scripts/bump-version.sh --plugin thinkies --bump patch
1.2.6
The preview shows the version would increment from 1.2.5 to 1.2.6. Since these are bug fixes without new features or breaking changes, patch is the appropriate level. After confirming this matches the changelog, I apply it:
$ .claude/scripts/bump-version.sh --plugin thinkies --bump patch --apply
Updated thinkies: 1.2.5 -> 1.2.6
Example 2: Minor bump for new features
The software plugin gained three new skills without changing existing ones. This is additive, not breaking, so minor bump is appropriate:
$ .claude/scripts/bump-version.sh --plugin software --bump minor
1.2.0
$ .claude/scripts/bump-version.sh --plugin software --bump minor --apply
Updated software: 1.1.2 -> 1.2.0
The bump reset the patch version to 0, following semantic versioning conventions where minor bumps clear the patch counter. This signals that 1.2.0 is a feature release rather than an incremental patch.
Example 3: Calculating version arithmetic without file changes
When planning a release or documenting version strategy, I can use the script as a calculator without touching any files:
$ .claude/scripts/bump-version.sh --version 2.5.8 --bump major
3.0.0
This shows what version would result from a major bump of 2.5.8, useful for discussions about release planning or understanding semantic versioning rules. Since no --plugin was specified, no files are touched regardless of whether --apply is present.
