version-release — Claude Code skill: what it does, how to install
version-release selects the correct SemVer bump and updates version tags across code packages, deploy manifests, and repository milestones.
MIT ★ 1,198 updated 2026-10-23
npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill version-release -a claude-codeWhat version-release does
This skill applies repository-wide Semantic Versioning rules to every release. It classifies pull requests into patch, minor, or major increments, though explicit version input from the user overrides automatic evaluation. You can preview changes without modifying files using node scripts/bump-release.js intermediate --dry-run --json.
The routine synchronizes the root and desktop package.json files, OpenAPI documentation, image tags in docker-compose.yml, Helm charts, and Kubernetes manifests. It also rebuilds Vitest UI snapshots, syncs extension manifests with npm run extensions:sync, and updates GitHub milestones across merged pull requests.
The repository requires the "Allow GitHub Actions to create and approve pull requests" setting; automation halts before remote writes if this permission is absent. Final verification relies on node --test server/__tests__/release-version-consistency.test.js to catch any metadata drift.
What it helps with
- choose the appropriate SemVer bump for a pull request
- update version tags across Kubernetes manifests, Helm, and Compose
- synchronize Claude and Codex plugin catalogs with root package versions
- attach milestone identifiers to unassigned merged pull requests on GitHub
Example prompts for the agent
- Evaluate the current git diff and determine whether the change set needs a patch, minor, or major release.
- Run the bump script dry-run for an intermediate release and inspect the JSON output.
- Run release-version-consistency.test.js to verify that all release surfaces match.
How to install version-release
1Skills CLI (Vercel)
npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill version-release -a claude-code2Manually: put the files in place
~/.claude/skills/version-release/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/version-release/
1Skills CLI (Vercel)
npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill version-release -a codex2Manually: put the files in place
.agents/skills/version-release/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill version-release -a cursor2Manually: put the files in place
.cursor/skills/version-release/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install hoangsonww/Claude-Code-Agent-Monitor .claude/skills/version-release2Manually: put the files in place
.github/skills/version-release/SKILL.md1Skills CLI (Vercel)
npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill version-release -a gemini-cli2Platform CLI
gemini skills install https://github.com/hoangsonww/Claude-Code-Agent-Monitor --path .claude/skills/version-releaseManually: put the files in place
.devin/skills/version-release/SKILL.mdThe legacy .windsurf/skills/ path still works
Claude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about version-release
How to install version-release in Claude Code?
Run npx skills add hoangsonww/Claude-Code-Agent-Monitor --skill version-release -a claude-code. The file will be placed in ~/.claude/skills/version-release/SKILL.md.
What does the version-release skill do?
It evaluates the scope of repository changes, calculates the SemVer increment, and propagates the new version string across all project manifests and docs.
Why does the prepare workflow use intermediate instead of minor?
The repository uses custom input names where minor increments the SemVer patch version, while intermediate applies the SemVer minor bump.
Source text
SKILL.md · MIT
--- name: version-release description: Choose and apply the correct semantic version bump for this repository. Use for every user-visible release, before merge when a change set should ship as patch, minor, or major, and whenever package/plugin/desktop version metadata must stay synchronized. --- # Version Release Use Semantic Versioning as the repository-wide release rule: - **Patch** (`X.Y.Z+1`) for backward-compatible bug fixes, documentation-only changes, dependency/security maintenance, internal refactors, and small user-visible improvements that do not create a substantial new capability. - **Minor** (`X.Y+1.0`) for backward-compatible feature additions or meaningfully larger product capabilities, including new workflows, pages, integrations, API fields/routes, or major UX surfaces. - **Major** (`X+1.0.0`) for backward-incompatible behavior, removed/renamed public contracts, required migrations, or fundamental product/architecture changes. When a change fits more than one category, use the highest applicable bump. When uncertain between adjacent categories, prefer the higher bump or ask the user before releasing. Never infer the bump from commit count, diff size, or elapsed time alone. When the user explicitly requests a concrete version, that instruction overrides automatic classification. State the override and synchronize the requested version exactly. ## Automated release preparation Use the manual **Prepare Release Bump** workflow for routine releases. Its repository-specific input names are intentionally different from standard SemVer labels: - `major` increments the first component: `X.Y.Z` to `X+1.0.0`. - `intermediate` increments the standard SemVer minor component: `X.Y.Z` to `X.Y+1.0`. - `minor` increments the standard SemVer patch component: `X.Y.Z` to `X.Y.Z+1`. Preview the exact plan locally without writes: ```bash node scripts/bump-release.js intermediate --dry-run --json ``` The workflow creates one branch, one coordinated commit, the exact open milestone, and one pull request. It also assigns that milestone to every merged default-branch PR that does not already have a milestone, including older omissions, while preserving existing assignments. Every automation-created commit ends with `Co-authored-by: hoangsonww <[email protected]>`. It requires the repository setting **Allow GitHub Actions to create and approve pull requests**, checks that prerequisite before remote writes, and keeps default workflow permissions read-only. It explicitly dispatches CI, file-header, and CLA checks because repository-token PR creation does not emit secondary workflow events. It never merges, force-pushes, tags, or publishes. Existing default-branch CI publishes only after a maintainer merges the PR. ## CCAM release workflow 1. Read the current root `package.json` version and summarize why the change is patch, minor, or major. 2. Update the root `package.json` and root lockfile. 3. Mirror the shipping version in `desktop/package.json` and `desktop/package-lock.json`. 4. Update the OpenAPI version example in `server/openapi.js`, then run `npm run openapi:yaml`. 5. Update the deployment surface, which carries the release in many places: `docker-compose.yml` (`ccam-dashboard` and `ccam-mcp` image tags), `deployments/helm/agent-monitor/Chart.yaml` (`version` **and** `appVersion`), every `deployments/kubernetes/**` manifest (`app.kubernetes.io/version` labels, `image:` tags, kustomize `newTag`), and `deployments/scripts/deploy.sh` (the `--tag` example and the `sed` image substitution). 6. Update the version shown in `DEPLOYMENT.md` and `docs/DEPLOYMENT.md` (the `ccam-dashboard:<version>` substitution example) and in `CITATION.cff` (`version:`). 7. Update version-sensitive UI snapshots when the rendered release string changes (the dashboard renders `UI build v<version>`; regenerate with `cd client && npx vitest run -u` and confirm the diff is only the version line). 8. Run `npm run extensions:sync` so every Claude/Codex plugin manifest and marketplace stays on the root release. 9. Update release/version documentation only where the concrete version is intentionally shown. 10. Create or reuse the open GitHub milestone named exactly `v<version>` for the new root version. Query all milestones before creating one. If an exact-title milestone already exists and is closed, stop and verify whether that version has already shipped instead of creating a duplicate. 11. Only after the new-version milestone step completes, paginate every pull request merged into the default branch and assign its returned numeric milestone ID to each PR with no milestone, including older omissions from earlier releases. Preserve every existing milestone assignment, verify each write with a fresh read, and fail if a final paginated query finds any merged PR still unmilestoned. 12. Identify the current open pull request containing the bump and assign it to that milestone. Read `closingIssuesReferences` from the PR and assign every linked closing issue to the same milestone. If the branch has no PR yet, create/reuse the milestone now and treat PR/issue assignment as an incomplete release step until the PR exists. 13. Verify the milestone on the PR and every linked issue with fresh GitHub reads. Do not infer completion from a successful edit command alone. 14. Run `npm run extensions:validate`, relevant tests/builds, and `ccam version` or `node bin/ccam.js version`. 15. Confirm only independently shipped packages remain on their own versions; do not bump `client`, `mcp`, `monitoring`, or VS Code extension packages unless those products are also being released. ## The authoritative surface list `server/__tests__/release-version-consistency.test.js` is the machine-checkable contract for a release bump. **Read it first and run it last** — it is more reliable than this document, because it fails when a surface drifts: ```bash node --test server/__tests__/release-version-consistency.test.js ``` It asserts root/desktop packages and lockfiles (including `packages[""].version`), the live and generated OpenAPI versions, Compose and Helm metadata, Kubernetes labels/images/kustomize tags, every generated plugin manifest, both marketplace catalogs, the deployment guides and `deploy.sh`, and that the independently versioned subprojects have *not* been dragged along. When you add a new file that carries the release version, add an assertion there in the same change. A surface with no assertion is a surface that will silently drift — `CITATION.cff` sat at `1.1.0` for many releases for exactly this reason. Cross-check with a repo-wide sweep for the *previous* version before finishing: ```bash previous_version="$(git show HEAD:package.json | node -p 'JSON.parse(require("fs").readFileSync(0,"utf8")).version')" grep -rFn "$previous_version" --exclude-dir=node_modules --exclude-dir=.git \ --exclude-dir=dist --exclude-dir=.worktrees . ``` `grep -F` matters: the dots in a version are regex wildcards otherwise, so a plain `grep -r` also matches unrelated strings like `2a0b11`. Reading the previous value from `HEAD:package.json` keeps the command runnable as-is mid-bump, before the change is committed. Expect zero hits outside `package-lock.json` history and deliberate historical references (for example "pre-v2.0.9 inflation" in the token-repair docs), which must stay pointing at the release they describe. ### Not release-tied — do not bump - `sw.js` and `client/public/sw.js` cache names (`landing-v2`, `dashboard-v2`) are cache generations, not release versions. `wiki/sw.js` is bumped when wiki *content* changes, which is the `update-project-docs` skill's job, not this one. - `deployments/helm/agent-monitor/values.yaml` uses `tag: ""` and falls back to the chart's `appVersion`. Leave it empty. - `client`, `mcp`, `monitoring`, and `vscode-extension` ship on their own versions and are asserted *not* to equal the root release. ## GitHub milestone workflow Use the repository resolved from the current checkout and the intended authenticated GitHub identity. Run `gh auth status` before any mutation and stop if the active account is not the account intended for the repository: ```bash repo="$(gh repo view --json nameWithOwner --jq .nameWithOwner)" version="$(node -p "require('./package.json').version")" milestone="v${version}" pr="$(gh pr view --json number --jq .number)" existing="$( gh api "repos/${repo}/milestones?state=all&per_page=100" --paginate \ --jq ".[] | select(.title == \"${milestone}\") | [.number, .state] | @tsv" )" ``` - If `existing` is empty, create the milestone with `gh api --method POST "repos/${repo}/milestones" -f title="${milestone}"`. - If it reports one open milestone, reuse it. - If it reports more than one match or a closed match, stop and resolve the repository state. Do not create another milestone with the same release title. - Only after the new-version milestone step completes, paginate every pull request merged into the default branch and assign its returned numeric milestone ID to every PR with no milestone, including older omissions. Preserve PRs that already have any milestone, verify every changed PR with a fresh read, then query all pages again and fail if any merged PR remains unmilestoned. - Assign the PR through `PATCH /repos/{owner}/{repo}/issues/{number}` with the numeric milestone returned by the completed milestone step. - Read linked issues with `gh pr view "$pr" --json closingIssuesReferences`. Assign each same-repository issue through the same numeric-milestone REST field. - If a closing issue belongs to another repository, stop and report it. Milestones are repository-scoped, so do not silently create or reuse a similarly named milestone in another repository. - Verify with `gh pr view "$pr" --json milestone,closingIssuesReferences`, then query each linked issue's `milestone`. ## Release guardrails - Do not hand-edit generated Codex metadata or marketplace files after `extensions:sync`. - Do not create or move a Git tag unless the user explicitly requested a release/tag operation. - Creating the matching GitHub milestone and assigning the current PR plus linked closing issues is part of a version bump, not a release/tag operation. - Do not create duplicate milestones, guess issue relationships from prose when `closingIssuesReferences` is available, or leave linked release work assigned to a different version. - Do not call a breaking change “minor” merely because compatibility can be restored later. - Do not leave root, desktop, OpenAPI, snapshots, deployment manifests, or generated plugin versions out of sync. - Do not blanket find-and-replace the version across the repo: it would pull the independently versioned subprojects along and rewrite deliberate historical references. - Do not hand-edit version surfaces when the automated workflow is available. Use `npm run release:bump -- <component>` only for a controlled local fallback. ## References - Repository release checklist: `references/version-checklist.md`
© hoangsonww · MIT · hoangsonww/Claude-Code-Agent-Monitor