Release Workflow

This skill handles the full release cycle for a Claude Code plugin that keeps its version in two files:

• .claude-plugin/plugin.json — the "version" field

• .claude-plugin/marketplace.json — the "metadata"."version" field

Both must always be in sync.

Workflow

1. Determine the bump type

Ask the user which kind of version bump they want — patch, minor, or major — unless they already specified it. Show the current version from plugin.json and what the new version would be for each option so the choice is concrete.

2. Run quality checks

Run make check (which verifies shared refs use correct paths and all shared files exist). This is the gate — if it fails, stop and report the errors so they can be fixed before retrying. Do not proceed past this step on failure.

3. Ensure we're on the right branch

The release branch must be named release/vX.Y.Z where X.Y.Z is the new version (after bumping).

• If already on release/vX.Y.Z matching the new version, stay on it.

• If on main or any other branch, create and switch to release/vX.Y.Z from the current HEAD.

• If on a release/ branch for a different version, warn the user and ask how to proceed — they may have started a release they want to abandon.

4. Bump the version

Edit both files to the new version string:

• .claude-plugin/plugin.json — change the "version" value.

• .claude-plugin/marketplace.json — change the "metadata"."version"

value.

Only change the version fields — don't touch anything else in either file. Verify both files now contain the same new version.

5. Commit and push

Stage .claude-plugin/plugin.json and .claude-plugin/marketplace.json , then commit with the message:

Bump version to vX.Y.Z

Push the branch to origin with -u to set up tracking.

6. Open a PR

Create a pull request targeting main with:

• Title: Release vX.Y.Z

• Body: A short summary noting the version bump from old to new. Keep it minimal — this is a version bump PR, not a changelog.

Report the PR URL back to the user.

Important details

• The version follows semver: MAJOR.MINOR.PATCH .

• Both plugin.json and marketplace.json must always have the same version.

• Always confirm the bump type with the user before making changes.

• If make check fails, the release is blocked — help the user fix the issues rather than skipping the checks.

• If there are uncommitted changes when starting, warn the user and ask whether to stash them, commit them first, or abort.