Where are versions stored and how are they kept in sync?

Versions live in two places: .claude-plugin/marketplace.json (marketplace entry) and plugins/ /.claude-plugin/plugin.json (individual plugin). The marketplace top-level version and metadata.version are schema versions and remain unchanged.

Does this script commit changes to Git?

No. The script reports the results and the user handles git diffs, commits, and changelog updates manually.

Can I bump multiple plugins or all plugins at once?

Yes. Use --plugin for specific plugins (repeat as needed) or --all to bump all plugins, along with the chosen bump type (major, minor, patch).

version-bump

Scanned

npx machina-cli add skill NikiforovAll/claude-code-rules/version-bump --openclaw

Files (1)

SKILL.md

3.5 KB

Version Bump Skill

Per-plugin version bumping for the Claude Code Handbook monorepo. Each plugin can have independent versions.

When to Use This Skill

Trigger this skill when users mention:

"bump version" or "bump the version"
"increment version" or "update version numbers"
Any mention of "major", "minor", or "patch" version changes

Version Locations

Each plugin has versions in two places (kept in sync):

.claude-plugin/marketplace.json → plugin entry version
plugins/<name>/.claude-plugin/plugin.json → individual plugin version

The marketplace top-level version and metadata.version are schema versions and remain unchanged.

Workflow Instructions

Step 1: List Current Versions

Show current plugin versions:

python .claude/skills/version-bump/scripts/validate_versions.py

Step 2: Ask User Which Plugin(s) to Bump

Ask the user:

Which plugin(s) to bump (can be multiple, or "all")
Which bump type: major, minor, or patch

Step 3: Execute Version Bump

Run the script with the selected plugins:

# Single plugin
python .claude/skills/version-bump/scripts/bump_version.py <bump_type> --plugin <name>

# Multiple plugins
python .claude/skills/version-bump/scripts/bump_version.py <bump_type> --plugin <name1> --plugin <name2>

# All plugins
python .claude/skills/version-bump/scripts/bump_version.py <bump_type> --all

Step 4: Report Results

After successful completion, display:

Plugins bumped with old → new versions
Next steps for git commit

CLI Reference

# Show help
python .claude/skills/version-bump/scripts/bump_version.py --help

# Error + list plugins when no --plugin flag
python .claude/skills/version-bump/scripts/bump_version.py patch

# Bump specific plugin(s)
python .claude/skills/version-bump/scripts/bump_version.py patch --plugin handbook-dotnet
python .claude/skills/version-bump/scripts/bump_version.py minor --plugin handbook --plugin handbook-extras

# Bump all plugins (legacy monorepo behavior)
python .claude/skills/version-bump/scripts/bump_version.py patch --all

Examples

Example 1: Bump Single Plugin

User: "Bump the version for handbook-dotnet"
Claude: "I'll check current versions first..."

[Runs validate_versions.py]

Claude: "handbook-dotnet is currently at 1.19.5. What bump type: major, minor, or patch?"
User: "patch"

[Runs: python bump_version.py patch --plugin handbook-dotnet]

Claude: "Done!
  handbook-dotnet: 1.19.5 → 1.19.6

Next steps:
1. git diff
2. git add . && git commit -m 'chore: bump handbook-dotnet to 1.19.6'"

Example 2: Bump Multiple Plugins

User: "Bump handbook and handbook-extras to a new minor version"

[Runs: python bump_version.py minor --plugin handbook --plugin handbook-extras]

Claude: "Done!
  handbook: 1.19.5 → 1.20.0
  handbook-extras: 1.19.5 → 1.20.0"

Example 3: Bump All Plugins

User: "Bump all plugins patch version"

[Runs: python bump_version.py patch --all]

Claude: "Done! All 13 plugins bumped from their current versions."

Notes

The script does NOT create git commits - user handles version control
Plugins can now have different versions (independent versioning)
Changelog updates are manual - user maintains CHANGELOG.md as needed

Source

git clone https://github.com/NikiforovAll/claude-code-rules/blob/main/.claude/skills/version-bump/SKILL.mdView on GitHub

Overview

This skill automates per-plugin version bumps for the Claude Code Handbook monorepo. It is used when users request to bump versions, prepare a release, or increment version numbers across the repository. Versions are kept in sync across two locations: marketplace.json and each plugin's plugin.json, while the top-level schema versions remain unchanged.

How This Skill Works

The skill lists current versions using a Python script, then asks which plugin(s) to bump and the bump type (major, minor, patch). It executes the bump with the bump_version.py script, updating both the marketplace and individual plugin versions. After success, it reports the changes and next steps for git commits; changelog updates are manual and handled by the user.

When to Use It

User requests to bump a specific plugin's version (major, minor, or patch).
User asks to bump multiple plugins at once.
User asks to bump all plugins in the monorepo.
User is preparing a release and needs version updates reflected in both marketplace and plugin files.
User wants to verify current plugin versions before proceeding with a release.

Quick Start

Step 1: List Current Versions: python .claude/skills/version-bump/scripts/validate_versions.py
Step 2: Decide Plugins and Bump Type: specify which plugin(s) and major/minor/patch
Step 3: Execute Bump: python .claude/skills/version-bump/scripts/bump_version.py <bump_type> --plugin <name> (or --all)

Best Practices

Run the current versions check first with the validate_versions.py script.
Clarify the exact bump type (major, minor, patch) and which plugin(s) to affect.
Only bump plugins you intend to release to avoid accidental changes.
Review old → new version mappings and communicate them clearly after the bump.
Remember: the script does not commit changes; perform git commits and changelog updates manually.

Example Use Cases

User: 'Bump the version for handbook-dotnet' Claude: 'I'll check current versions first...' [Runs validate_versions.py] Claude: 'handbook-dotnet is currently at 1.19.5. What bump type: major, minor, or patch?' User: 'patch' [Runs: python bump_version.py patch --plugin handbook-dotnet] Claude: 'Done! handbook-dotnet: 1.19.5 → 1.19.6' Next steps: git diff; git add . && git commit -m 'chore: bump handbook-dotnet to 1.19.6''
User: 'Bump handbook and handbook-extras to a new minor version' [Runs: python bump_version.py minor --plugin handbook --plugin handbook-extras] Claude: 'Done! handbook: 1.19.5 → 1.20.0; handbook-extras: 1.19.5 → 1.20.0'
User: 'Bump all plugins patch version' [Runs: python bump_version.py patch --all] Claude: 'Done! All 13 plugins bumped from their current versions.'
User: 'Prepare a release and ensure marketplace and plugin versions are aligned' Claude: 'Validated current versions, executed patch/minor/major bumps as requested for the selected plugins, and prepared a summary of changes for the release notes.'
User: 'I want to bump two plugins to patch after a hotfix' Claude: 'Executing patch bump for handbook and handbook-fixes; results show old → new versions for each.'

Frequently Asked Questions

Add this skill to your agents