| name | release-plugin |
| description | Cut a new version of a Claude Code plugin in the current working directory — bump .claude-plugin/plugin.json, update README version references, commit, tag, push, and create a GitHub Release with notes summarizing commits since the last tag. Use when shipping a plugin update so end-user auto-update paths (claude-plugins.dev, ClaudePluginHub, marketplace listings) pick up the new version. Typical trigger: user says "release the plugin", "ship a new version", "cut v0.x.y", "tag a release". |
Release Plugin
Codex Notes
- This skill still targets Claude Code plugin repos that ship from
.claude-plugin/plugin.json.
Release the Claude Code plugin in $CWD as a new semver-tagged version. Picks up all changes since the last tag into one release.
Preconditions
- CWD is a Claude Code plugin repo — has
.claude-plugin/plugin.json with a "version" field.
- CWD is a git repo with a clean working tree (
git status --porcelain empty).
- Current branch is
main (or explicitly confirmed by user).
gh CLI authenticated with write access + repo scope.- All desired commits are already merged to the branch being released.
Flow
1. Snapshot the state
- Read
.claude-plugin/plugin.json — capture current "version" and "name".
- Get the latest tag:
git tag --sort=-version:refname | head -1.
- List commits since that tag:
git log <last-tag>..HEAD --oneline.
- If no commits since last tag → stop. No release needed.
- If no tags at all → this is the first release; treat the next version as the initial tag.
2. Decide the new version
Scan the commit subjects. Pick a bump per semver:
- Patch (
x.y.Z+1) — bug fixes, doc updates, internal tooling, attribution. No API/contract changes.
- Minor (
x.Y+1.0) — new skills, new commands, new catalog entries, additive features. No breaking changes.
- Major (
X+1.0.0) — breaking changes to skill names / slash commands / frontmatter contracts.
Default bump: patch unless user asks otherwise or commits reveal a new feature. State the chosen bump + reasoning, give the user a chance to override before proceeding.
3. Apply the version bump
- Edit
.claude-plugin/plugin.json: "version": "<new>".
- Check README for any version-referencing line (usually a
Status: or What's new in header). If found, update to the new version — many plugin CIs enforce manifest↔README alignment and will fail invariant checks otherwise.
- Skim README's intro/"What's new" section. If commits include user-visible changes, ask the user whether to append a "What's new in v" block listing them. Do not invent features — the list must be derivable from the commit log.
4. Commit + tag + push
git add .claude-plugin/plugin.json README.md
git commit -m "Ship v<new>: <one-line summary>"
git push origin main
git tag -a v<new> -m "v<new>: <one-line summary>"
git push origin v<new>
Commit message body should reference the commit range (e.g., "N commits since v") and the top 3-5 user-visible changes by short-sha.
5. Create the GitHub Release
Use gh release create v<new> with a structured body:
- Headline: one-line elevator for the release
- User-visible improvements — group by area: Skills / Catalog / Metadata. Reference commits by short-sha in parens. Skip internal-only changes (test infra, CI plumbing) from this section.
- Engineering additions (no user impact) — mention briefly so contributors know what landed
- Upgrade — one paragraph on how end users pick up the release (usually: re-install via the skill, or trust auto-update to crawl)
- Acknowledgments — only if upstream work was meaningfully incorporated this release
Body derived from the commit log, not invented. Use gh release create v<new> --title "..." --notes "..." with a heredoc.
6. Confirm end-state
gh release view v<new> shows the release is live.git log --oneline | head -5 shows the tag-bump commit on main.- Optional: note in the summary that marketplaces (claude-plugins.dev, ClaudePluginHub) will re-crawl on their own cadence and push the update to installed users.
Hard rules
- Never release from a dirty working tree. Even untracked files unrelated to the plugin can signal unfinished work. If
git status --porcelain is non-empty, stop and ask.
- Never invent features in the release notes. Every bullet must trace to a committed change (cite short-sha when possible).
- Never skip the version bump in
plugin.json. That's the one file end-user auto-update paths actually read; without it, re-crawling marketplaces won't push the update to installed plugins.
- Never push a tag without a matching commit on main first. A tag on a commit that's not yet pushed creates a "phantom" release that downstream tooling can't resolve.
- Never force-push or retag. If something went wrong, cut a new patch version (v0.2.1 → v0.2.2). Tags are immutable for downstream trust.
- Never commit or push without explicit user confirmation when the diff is more than the version bump + README alignment. Releases are user-visible; the user should explicitly OK anything substantive.
When NOT to use
- Plugin is in active development with no logical release point (wait).
- Commits are all internal tooling with no user-visible change (wait — no signal to publish).
- Repo is not a Claude Code plugin (no
.claude-plugin/plugin.json).
- User wants to fix a bad release — see "Hard rules": cut a new version instead of mutating the broken one.
Related patterns
v0.x.0 minor bumps typically add new catalog entries, new skills, or new agent-team roles. Reserve for substantive additions.v0.x.y+1 patch bumps are the common case during polish iterations — doc fixes, prompt tuning, dependency pins, attribution.- Plugins with a
test-invariants.sh that enforces manifest↔README alignment (like github-agent-runner) require the README bump in step 3 or the invariant test fails in CI after the tag commit.
