version-bump
/version-bump
Use for version bumps on explicit request or as the pre-merge step of a PR land. Never infer from finished, reviewed, green, or draft-ready work. Assigns SemVer.
- Author
- bostonaholic ↗
- Repository
- team ↗
- Licence
- MIT
- Last repository change
- 22.10.2026
Assessment and security
- Files in this package
- 1
- Scripts
- 0
- HTML comments
- 0
- URLs in SKILL.md
- 4
No signals detected. Repository changed on 22.10.2026, without references to retired models or APIs.
MIT, open: use and modify while retaining author attribution.
What it does and when to use it
Use for version bumps on explicit request or as the pre-merge step of a PR land. Never infer from finished, reviewed, green, or draft-ready work. Assigns SemVer.
Original author description
Use for version bumps on explicit request or as the pre-merge step of a PR land. Never infer from finished, reviewed, green, or draft-ready work. Assigns SemVer.
How it works
- Precondition — explicit land intent
- Steps
SKILL.md preview
---
name: version-bump
description: 'Use for version bumps on explicit request or as the pre-merge step of a PR land. Never infer from finished, reviewed, green, or draft-ready work. Assigns SemVer.'
---
# Version Bump — version a project at land time
This repository's own versioning procedure. `AGENTS.md` declares it as the
pre-merge step, so the land command runs it before merging. Tagging and the
GitHub release are **not** part of it; `release-on-merge.yml` does that on
merge. When invoked directly, run this skill **before** the land command,
against the version of `main` you intend to land onto. When a land command
invokes this skill, return to it after step 8.
## Precondition — explicit land intent
**Why:** the bump is computed against the base branch's tip at this moment; a
bump made before the land goes stale when another PR merges, and the pre-merge
guard then denies the merge.
**This skill fires only on explicit land intent**, meaning one of:
- The user asked to land: "ship it", "land the PR", "land this".
- The user asked for the bump itself: "bump the version", "version this PR".
- A land command is already in flight and reached the project's pre-merge steps.
**Never infer land intent.** None of the following is a cue to bump:
- The work is finished, the review passed, or CI is green.
- A draft PR is about to be opened, or was just opened. A drafted PR carries
**no** version: the bullet goes under `## [Unreleased]` and nothing else moves.
- The invariant script exited 1. That exit states a precondition for *merging*,
expected for a runtime PR's whole review lifetime, never a request to bump now.
With no land intent, **stop and say so.** Report that the branch will need a
bump before it can merge, and wait for the user. Do not bump "to be helpful".
## Steps
### 0. Runtime-vs-dev gate — does this PR warrant a bump at all?
**Run this before everything else. Most steps below only apply if it says yes.**
The quick look is orientation only — it never decides the exit:
`git diff "origin/<default>...HEAD" --name-only`. The decision comes from **the
invariant run**, the same invocation contract the pre-merge guard enforces:
1. Resolve the default branch by asking GitHub (`gh repo view`), falling back
to the local `origin/HEAD` ref. Never a guessed `main`. If both fail, stop:
no verdict.
2. `git fetch origin <default>` must succeed. Never degrade to a stale base for
a verdict.
3. The fetched `origin/<default>` tip must be an ancestor of the branch tip. If
the branch is behind, **stop**: rebase onto `origin/<default>` and re-enter
step 0.
4. Run the script with `HEAD_SHA` = the local branch tip and `BASE_SHA` = the
fetched `origin/<default>` **tip** — never a pre-computed merge-base, and
never a hand-rolled two-dot diff.
```bash
DEFAULT=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null)
DEFAULT=${DEFAULT:-$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||')}
[ -n "$DEFAULT" ] || { echo "cannot resolve the default branch — no verdict"; exit 1; }
git fetch origin "$DEFAULT" || { echo "fetch failed — no verdict"; exit 1; }
git merge-base --is-ancestor "refs/remotes/origin/$DEFAULT" HEAD \
|| { echo "behind base — rebase onto origin/$DEFAULT, re-enter step 0"; exit 1; }
HEAD_SHA=$(git rev-parse HEAD) BASE_SHA=$(git rev-parse "refs/remotes/origin/$DEFAULT") \
.claude/scripts/version-bump-required.sh
```
**Read the outcome by exact output match — the signal rule, default-deny:**
- Exit 0, stdout starting `OK: runtime_changed=false bumped=false` → dev-only
and final. **DO NOT BUMP.** Skip every step below. Leave the version
untouched, do **not** cut the changelog, and land with the plain
conventional title (`<type>: <subject>`). On a re-entry whose PR title
still carries a stale `vX.Y.Z` prefix from an earlier bump, strip it now
(`gh pr edit --title`) — the title backstop never strips a stale prefix,
and this is the one step-8 action a no-bump exit still owes. Then go
straight to the land command. This exit **requires** that OK line — the quick look
alone never authorizes it.
- Exit 0, stdout starting `OK: runtime_changed=true bumped=true` → already
bumped (a recovery re-entry). Never re-bump — proceed to the land command.
- Exit 1, verdict containing `cannot merge until version-bump runs at land time`
→ bump warranted. It is actionable here only because the land-intent
precondition already passed; read outside a land it states a merge
precondition and nothing more.
- On a branch with **no** `chore(version)` commit: **continue to step 1**.
Every other exit-1 verdict in this list stops.
- On a branch **already carrying** a `chore(version)` commit: the bump went
stale (a rebase moved the fork point). Stop — drop the bump commit, undo
the changelog cut, reset the title, and re-enter step 0.
- Exit 1, verdict containing `must land with no bump` → wrongful bump. Stop —
drop the commit, undo the cut, and re-run step 0.
- **Anything else** — a non-semver version, a merge-base or diff failure, or
unrecognized output — stops in both directions. Surface the message
verbatim. A hard script error never means "keep going".
This is a hard gate, not a judgment call.
### 1. Decide the bump level
Reached **only when step 0 said a bump is warranted**; the only question is how
big the bump is.
```bash
# Re-derive the base: shell variables do not persist from step 0's call.
DEFAULT=$(gh repo view --json defaultBranchRef --jq .defaultBranchRef.name 2>/dev/null)
DEFAULT=${DEFAULT:-$(git symbolic-ref refs/remotes/origin/HEAD 2>/dev/null | sed 's|^refs/remotes/origin/||')}
: "${DEFAULT:?cannot resolve the default branch}"
git log "origin/$DEFAULT..HEAD" --oneline
git diff "origin/$DEFAULT...HEAD" --stat
```
[SemVer 2.0.0](https://semver.org/spec/v2.0.0.html), quoted verbatim. Items 6,
7, and 8 each carry an `x > 0` precondition:
| Item | Normative rule | Scope |
|------|----------------|-------|
| 6 | PATCH "MUST be incremented if only backward compatible bug fixes are introduced. A bug fix is defined as an internal change that fixes incorrect behavior." | `x.y.Z \| x > 0` |
| 7 | MINOR "MUST be incremented if new, backward compatible functionality is introduced to the public API." | `x.Y.z \| x > 0` |
| 8 | MAJOR "MUST be incremented if any backward incompatible changes are introduced to the public API." | `X.y.z \| X > 0` |
If the version starts `0.`, none of those three binds. Item 4 governs: "Major
version zero (`0.y.z`) is for initial development. Anything MAY change at any
time. The public API SHOULD NOT be considered stable." Item 5: "Version 1.0.0
defines the public API." The spec assigns no level pre-1.0, so the decision
below uses the same observable-change rule before and after 1.0.0.
Ask these in order. **The first yes wins.** Judge the *change*, never the
commit subject:
1. **Can a plugin user observe the difference?** → **minor**. Anything that
changes what they type, what they get back, or what the project does on
their behalf is observable: a command's name or arguments
(`argument-hint`), documented behavior, whether a step prompts them, an
artifact's format or frontmatter schema, an agent's model, or tool access.
New and changed capability both land here.
2. **Otherwise** → **patch**: internal-only *and* backward compatible — prose
that clarifies without changing an instruction, a comment, restructuring
that preserves behavior. Item 6 requires both qualifiers, not just a `fix:`
subject. Expect patch to be rare for projects that ship instructions a
model reads. Do not widen patch to make the cadence feel familiar.
**`major` is unreachable while the version starts `0.`** A breaking change
pre-1.0 is a **minor**, not a major. If a change looks like it warrants major,
that is a signal to **ask whether it is time to declare 1.0.0** — a deliberate
decision, never a side effect of this skill.
State the chosen level and which question decided it. A level that needed a
judgment call means the observability question was not actually answered —
answer it rather than asking the user.
### 2. Compute the next version
```bash
bash .claude/scripts/next-version.sh <level>
```
### 3. Bump all six version strings
The version lives in **six places across five files**:
| File | Occurrences |
|------|-------------|
| `.claude-plugin/plugin.json` | 1 (`version`) |
| `.claude-plugin/marketplace.json` | 2 (`metadata.version` **and** `plugins[0].version`) |
| `.codex-plugin/plugin.json` | 1 (`version`) |
| `package.json` | 1 (`version`) |
| `plugin.json` (repo root) | 1 (`version`): what Antigravity reports |
Each host shows the version in its own manifest: Codex reads
`.codex-plugin/plugin.json` in preference to the Claude manifest; Antigravity
reads the root `plugin.json`, which sits at the root rather than in a directory
of its own because that host resolves `skills/` and `agents/` as siblings of
its manifest. A stale one makes the same release look like two different
versions depending on the host.
Edit all five files, then prove it:
```bash
grep -rn '"version"' package.json plugin.json .claude-plugin/plugin.json \
.claude-plugin/marketplace.json .codex-plugin/plugin.json
```
All six lines must show the **new** version. Zero may still show the old one.
### 4. Cut the changelog section
In `CHANGELOG.md` (Keep a Changelog format, entry style per
`skills/team-pr/references/changelog.md`):
- Move the entire `[Unreleased]` body into a new `## [X.Y.Z] - YYYY-MM-DD`
(today's date) section inserted directly **below** `## [Unreleased]`. Leave
`## [Unreleased]` in place, now empty again.
- Re-point the link-reference footer:
- `[Unreleased]` compare base → `vX.Y.Z...HEAD`
- Add `[X.Y.Z]: https://github.com/<owner>/<repo>/compare/v<prev>...vX.Y.Z`
This section becomes the GitHub release notes verbatim — write it for a reader
deciding if the upgrade is worth it. Any links must be **absolute URLs**:
relative paths (e.g. `docs/versioning.md`) render as dead links on the release
page.
**Empty `[Unreleased]`.** A PR that reached this step changed runtime files; an
empty `[Unreleased]` on it means nobody wrote the user-facing bullet. **Derive
at least one bullet from the PR's runtime commits**
(`feat:`/`fix:`/`perf:`/`security:`, in that entry style). Never write an empty
section (`release-on-merge.yml` errors on empty release notes).
Empty `[Unreleased]` **and** no runtime change is not this case: that PR must
have stopped at **step 0**, with no bump and no changelog cut. Do not invent a
bullet to justify a bump that step 0 already declined. Go back and land plain.
### 5. Land-time consistency assertion
Run it after the changelog cut (so the dated section exists) and **before
committing**:
```bash
bash .claude/scripts/check-version-consistency.sh
node -e "['.claude-plugin/plugin.json','.claude-plugin/marketplace.json','.codex-plugin/plugin.json','.agents/plugins/marketplace.json','plugin.json','package.json'].forEach(f=>JSON.parse(require('fs').readFileSync(f)));console.log('JSON OK')"
```
The released-section and footer-compare-link invariants hold only after the
cut, so assert them inline here:
```bash
V=$(jq -r .version .claude-plugin/plugin.json)
OWNER_REPO=$(gh repo view --json nameWithOwner --jq .nameWithOwner)
ESC=$(sed 's/\./\\./g' <<<"$V")
grep -qE "^## \[$ESC\] - [0-9]{4}-[0-9]{2}-[0-9]{2}$" CHANGELOG.md \
|| { echo "::error::no '## [$V] - YYYY-MM-DD' section — the cut did not land"; exit 1; }
grep -qE "^\[$ESC\]: https://" CHANGELOG.md \
|| { echo "::error::no footer compare link for $V"; exit 1; }
grep -q "\[Unreleased\]: https://github.com/$OWNER_REPO/compare/v$V...HEAD" CHANGELOG.md \
|| { echo "::error::[Unreleased] footer does not compare from v$V"; exit 1; }
echo "OK: land-time consistency holds"
```
If any check fails, **stop before committing** and fix the cut.
### 6. Commit
Commit the bump as its own commit in the PR branch:
```bash
git add .claude-plugin/plugin.json .claude-plugin/marketplace.json \
.codex-plugin/plugin.json plugin.json package.json CHANGELOG.md
git commit -m "chore(version): X.Y.Z"
```
### 7. Assert the bump invariant
Re-run the invariant run from step 0 — the head is now the branch tip carrying
the `chore(version)` commit. Require exit 0 with stdout starting
`OK: runtime_changed=true bumped=true`.
This runs **before any remote change** (the title edit in step 8 is remote).
On any other outcome, stop: drop the `chore(version)` commit, undo the
changelog cut, and land plain — nothing has left the machine, so the recovery
is purely local.
### 8. Title the PR
`vX.Y.Z <type>: <subject>` — e.g. `v1.4.0 feat: add a design review gate`. Set
it on the existing PR (`gh pr edit --title`). The `PR title sync` workflow is a
backstop — do not rely on it.
A re-entry path that runs after a title already exists must reset it: the
stale-bump recovery re-titles with the recomputed version, and a re-entry that
ends at "no bump" strips the `vX.Y.Z` prefix explicitly — the title backstop
never strips a stale prefix.
Return to the land command to push, wait for CI, and squash-merge.
Versions
| Repository | Score | Licence |
|---|---|---|
| This page · bostonaholic/team | 100 | MIT |
| thedotmack/claude-mem | 100 | Apache-2.0 |
| meteor/meteor | 100 | MIT |
| fabiensalles/claude-marketplace | 100 | MIT |
| NikiforovAll/claude-code-rules | 100 | Apache-2.0 |
| firstloophq/nomendex | 100 | MIT |
Database snapshot: 13.11.2026 · package version 817ce736ee04 (SHA-256 digest of the entire package)
Downloads in the last 30 days: 0 · ranking
Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.
Similar skills
- 86bump-version
Bump plugin version. Use when you need to increment a plugin's version number. - 84release
Adds the release that every PR must carry, and runs before creating or pushing any PR. Bumps the plugin version and writes changelog entries: gathers merged PRs since the last tag plus unmerged current-branch changes, decides the semver bump, and commits the release onto the… - 90bump
This skill should be used when the user asks to "bump version", "bump new version", "release new version", "update version", "create a release", or any task involving incrementing the crux-hive plugin version, updating the changelog, and creating a release PR. - 100bump-version
Bump the membrowse package version (pyproject.toml and the Claude plugin manifests), open a PR, wait for CI to pass and squash-merge it. Use when the user asks to bump the version, cut a patch/minor/major release version, or run /bump-version. Accepts an optional argument -… - 100umb-bump-version
Bump the Umbraco CMS version across all required files. Use when the user asks to bump, update, or set the version number — e.g., "bump version to 17.3.4", "set version to 18.0.0-rc", "update version". Accepts the target version as an argument. - 90release-tag
Cut a release by determining the SemVer bump from history, updating version files across any stack, refreshing the changelog, creating an annotated (optionally signed) Git tag, and pushing the release safely after pre-flight checks. Use when tagging a version, bumping the…