Analyze PR changes and prepare semantic version bumps with changelog entries. Use this skill when: preparing a branch for PR creation, bumping version before merge, finalizing a PR for release, checking if version was bumped, verifying changelog entries. Trigger phrases: "bump version", "version bump", "prepare release", "prepare PR", "finalize PR", "check version", "verify bump", "semver", "changelog", "what version should this be", "ready to merge", "pre-merge check", "update version", "draft changelog", "release prep", "version check", "bump and PR".
Analyze git changes since branching from main, recommend a semantic version bump, update version files, draft a changelog entry, and prepare the branch for PR creation.
{PLUGIN_ROOT} = Plugin root directory (where .claude-plugin/plugin.json lives)
When this skill references files like {PLUGIN_ROOT}/lib/patterns/version-discovery.md, read from the plugin root, not relative to this skill folder.
| Does | Does NOT |
|---|---|
| Analyze changes since main | Run release scripts |
| Detect version files and changelog | Push tags |
| Recommend semver bump with evidence | Merge branches |
| Update version files and changelog | Deploy or publish |
| Commit version bump changes | |
Push branch and create PR via gh pr create |
| Mode | Trigger | Purpose |
|---|---|---|
| Prepare (default) | prepare, bump, or no args | Bump version, draft changelog, commit, push, create PR |
| Finalize | finalize, verify, check | Verify version bump and changelog exist before merge |
Establish the working context.
Verify not on main branch:
git branch --show-current
If on main or master, STOP with: "Switch to a feature branch first. Version bumps should not be done directly on main."
Identify base branch:
git merge-base main HEAD
This is the point where the current branch diverged from main.
Detect mode from user input:
Report context:
Branch: feature/my-feature
Base: main (diverged at abc1234)
Mode: Prepare
Scan the repository for version infrastructure.
Read pattern reference:
Read {PLUGIN_ROOT}/lib/patterns/version-discovery.md for the detection algorithm.
Scan for version files in priority order:
package.yaml → look for version: fieldpackage.json → look for "version": fieldpyproject.toml → look for version = field.claude-plugin/plugin.json → look for "version": fieldCargo.toml, setup.cfg, VERSIONScan for changelog:
CHANGELOG.md, CHANGES.md, HISTORY.mdExtract semver rules from:
CLAUDE.md → look for ## Versioning sectionRELEASING.md → look for semantic versioning guidanceCONTRIBUTING.md → look for versioning sectionDetect release automation:
scripts/release.sh.github/workflows/release.yamlMakefile or Justfile release targetsCheck for additional version files that should stay in sync:
package.yaml has version, also check .claude-plugin/plugin.json## Version Infrastructure
| Component | Found | Details |
|-----------|-------|---------|
| Version file | package.yaml | v3.0.0 |
| Changelog | CHANGELOG.md | Keep a Changelog format |
| Semver rules | CLAUDE.md | 5 rules extracted |
| Release script | scripts/release.sh | Tag-based release |
| Additional version files | .claude-plugin/plugin.json | v3.0.0 (in sync) |
Examine all changes since branching from main.
Read pattern reference:
Read {PLUGIN_ROOT}/lib/patterns/change-classification.md for the classification algorithm.
Collect commit history:
git log main..HEAD --oneline --no-merges
Collect diff summary:
git diff main...HEAD --stat
git diff main...HEAD --name-status
Classify changes using the pipeline from change-classification.md:
Build evidence table:
| Evidence | Source | Bump Signal |
|---|---|---|
| ... | ... | ... |
Map classified changes to a semver recommendation.
Determine bump level:
Calculate new version:
X.Y.Z (from Phase 2)X+1.0.0X.Y+1.0X.Y.Z+1Present recommendation:
## Recommendation: MINOR bump
Current: 3.0.0 → Recommended: 3.1.0
### Evidence
| Evidence | Source | Signal |
|----------|--------|--------|
| New consequence type `foo` added | consequences.yaml diff | MINOR |
| feat: Add foo consequence | commit abc1234 | MINOR |
### Reasoning
New type added with no breaking changes. All existing types unchanged.
Offer override:
Apply the version bump and draft changelog.
Only runs in Prepare mode. In Finalize mode, skip to Phase 6.
Update version file(s):
package.yaml).claude-plugin/plugin.json)Draft changelog entry:
### Added - New features### Changed - Changes to existing functionality### Fixed - Bug fixes### Removed - Removed features### BREAKING CHANGES - For MAJOR bumpsPresent draft for review: Show the exact changes that will be made to each file.
After user confirms, commit:
git add <version-files> <changelog>
git commit -m "chore: Prepare release vX.Y.Z"
Push branch to remote:
git push -u origin <branch-name>
Create pull request:
Reference {SKILL_ROOT}/resources/pull-requests.md for gh pr create syntax.
gh pr create --title "Release vX.Y.Z" --body "$(cat <<'EOF'
## Summary
Version bump: A.B.C → X.Y.Z (MAJOR|MINOR|PATCH)
### Changelog
<paste changelog entry from step 2>
---
Prepared by `/pr-version-bump`
EOF
)"
Capture and store the PR URL from the output.
Summarize what was done and offer next steps.
## Version Bump Complete
- Version: 3.0.0 → 3.1.0
- Files updated: package.yaml, .claude-plugin/plugin.json
- Changelog: CHANGELOG.md updated with [3.1.0] entry
- Commit: abc1234 "chore: Prepare release v3.1.0"
- PR: https://github.com/hiivmind/hiivmind-blueprint-lib/pull/XX
### Next Steps
1. Review the PR and get approval
2. Merge the PR -- GitHub Actions will automatically create a tagged release
In Finalize mode, Phase 6 checks instead of executes:
Check version bumped:
Check changelog updated:
Report results:
## Pre-Merge Verification
| Check | Status | Details |
|-------|--------|---------|
| Version bumped | PASS | 3.0.0 → 3.1.0 |
| Changelog entry | PASS | [3.1.0] - 2026-02-07 with 3 items |
| Version files in sync | PASS | package.yaml and plugin.json both 3.1.0 |
Ready to merge.
Or if checks fail:
## Pre-Merge Verification
| Check | Status | Details |
|-------|--------|---------|
| Version bumped | FAIL | Still 3.0.0 - no bump detected |
| Changelog entry | FAIL | No [3.1.0] entry found |
Run `/pr-version-bump prepare` to fix.
| Error | Action |
|---|---|
| Not a git repository | STOP: "This directory is not a git repository." |
No main branch | Try master, then STOP if neither exists |
| No commits since main | STOP: "No changes to version. Branch is up to date with main." |
| No version file found | STOP: "No version file detected. Create a package.yaml, package.json, or pyproject.toml first." |
| Uncommitted changes | Warn: "You have uncommitted changes. Commit or stash them before bumping version." |
| Version already bumped | In Prepare mode, warn and offer to re-bump or skip |