How to use the Version Bump & Release agent skill

What is an agent skill and what does this one do?

An agent skill is a folder containing a SKILL.md file with instructions that Claude can load when a request matches the skill's description. The agent then follows those instructions instead of improvising. This skill is named version-bump and is described as an automated semantic versioning and release workflow for Claude Code plugins.

In practice, the skill makes the agent work through a release in order. It decides whether a change is a PATCH (bug fixes), MINOR (features) or MAJOR (breaking) increment, updates the version string in every file that carries it, runs the build-and-sync command, commits, tags and pushes, creates a GitHub release, and regenerates CHANGELOG.md from GitHub release notes. It also checks the npm publish run and can draft and post an announcement to X.

• Version files: package.json, plugin/package.json, .claude-plugin/marketplace.json, several plugin.json manifests (Claude, Codex, Qoder, Grok, Cursor and others), openclaw/openclaw.plugin.json, dsh/package.json, and the version badge in README.md.
• Release actions: git commit, annotated git tag, git push, gh release create.
• Publishing: done by the tag-triggered GitHub Actions workflow through npm trusted publishing, not by the agent running npm publish.

How do you install the version-bump skill?

Download the skill ZIP from this page and unzip it. The skill folder needs to end up in a skills directory that Claude Code reads. You have two options.

For a personal install, unzip it into ~/.claude/skills/. For a project-only install, unzip it into the .claude/skills/ folder inside your project. Project installs are useful when only one repository should have the release checklist.

If you use the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.

• Personal: ~/.claude/skills/
• Project: .claude/skills/ inside the repository
• Claude apps: Settings → Capabilities → Skills

How do you trigger the skill with a natural request?

You do not need a special command. Describe the release in plain language and mention the version you want. The skill's description covers version increments, manifests, build verification, git tagging, GitHub releases and changelog generation, so requests about those topics should match it.

Be specific about the bump type and the version. The workflow starts with an analysis step that classifies the change, so telling the agent up front avoids a guess. Before starting, the skill also asks for detailed release notes, so have a summary of the changes ready.

• Cut a patch release for the bug fixes merged since the last tag.
• Bump claude-mem to a minor version for the new search feature, then run the full release.
• Release version X.Y.Z of this plugin and check the npm publish run afterwards.
• Check that every version file matches before we tag anything.

What does a release run look like?

The skill works through a numbered workflow. Each step is a concrete command or check, and the final step is git status, which must show a clean tree with everything pushed. The skill's checklist includes confirming that a grep for the old version returns zero hits before tagging.

Verification is built in. Before committing, the agent checks that the new version appears in all fourteen JSON manifests and that the README badge reads the new version. It uses npm run build-and-sync rather than plain npm run build, because the skill says plain build can leave the local marketplace and worker out of sync.

• Verify coverage: git grep -l for the old version should list the fourteen JSON files.
• Build and sync: npm run build-and-sync.
• Commit: git add -A and a chore commit message.
• Tag and push: an annotated tag, then git push origin main and the tag.
• GitHub release: gh release create with release notes.
• Changelog: npm run changelog:generate, then commit and push CHANGELOG.md.

How does npm publishing work in this skill?

The agent does not publish to npm itself. Pushing the version tag triggers the workflow file .github/workflows/npm-publish.yml, which builds, runs a smoke check and publishes using npm trusted publishing through GitHub OIDC, so no npm token is needed. The skill tells the agent to watch that run with gh run list and gh run watch.

If the run fails, the skill says to read the failing step with gh run view and re-run only transient failures. It also forbids moving or recreating a pushed tag. After publishing, the agent verifies the exact version and the latest dist-tag with npm view.

• Do not run npm publish locally; the skill says only the workflow publishes and attaches provenance.
• A fix to code or the workflow ships in a new patch release, not by re-tagging.
• Renaming the workflow file breaks publishing until the trusted publisher entry on npmjs.com is updated.

What do you need before using it?

The skill assumes a working repository and tools that the agent can call. It will not run correctly on a generic project without changes, because the file list, scripts and npm workflow are specific to claude-mem.

Check these requirements before you start.

• git, with a GitHub remote for the repository.
• GitHub CLI (gh), authenticated with permission to create releases.
• Node.js and npm, with the project's build-and-sync and changelog:generate scripts.
• npm trusted publishing already configured for the workflow, so the agent needs no npm token.
• Optional: an image-generation tool, and a browser already logged in to the X account used for announcements.

What safety limits should you know?

This skill runs scripts and uses the network. It commits everything with git add -A, pushes to main, pushes tags, and creates public GitHub releases. The skill itself says tags are hard to undo and discourages moving or recreating them. Only use it with a person reviewing each step, and only if you have push and release rights.

The X announcement step is limited. The skill says to post only from a browser already logged in as @Claude_Memory, to skip the post if no such session exists, and never to sign in or switch accounts. It also requires npm verification before posting.

• Do not run it unattended.
• Review git status and the diff before the commit and push steps.
• Confirm the release notes before the GitHub release is created.
• If no browser is logged in as the project account, the agent skips the X post and reports that.

Tips for a smoother release

Keep a running list of user-facing changes during the cycle. The skill asks for detailed release notes at the start, and those notes feed the GitHub release and the regenerated changelog. Check the manifest list in SKILL.md against the repository when a new plugin manifest has been added, because the skill says to update the list in that case.

The file name for the changelog script differs between places in the source material. SKILL.md says the script is scripts/generate-changelog.js while the file listing names scripts/generate_changelog.js. Confirm which name exists in your repository before running the changelog step.

• Read the verify step output before committing; a missed manifest is the main risk.
• Watch the publish run with gh run watch rather than assuming success.
• If you are adapting the skill for another project, rewrite the file list first, since wrong paths could mis-version files.