plugin-semver

name	plugin-semver
description	Semver and version-field discipline for Claude Code plugin changes. TRIGGER when: modifying any file inside a plugin directory (tree contains .claude-plugin/plugin.json), or editing a .claude-plugin/marketplace.json. DO NOT TRIGGER when: editing skills/agents outside any plugin — e.g. user-scope stowed skills.
user-invocable	false

Plugin semver

Fires when modifying files inside a Claude Code plugin or a marketplace manifest.

Version field: one location only

Every behavior-affecting change to a plugin requires bumping version in that plugin's .claude-plugin/plugin.json. Never add a version field to that plugin's entry in .claude-plugin/marketplace.json. Claude Code resolves plugin.json first and silently masks any marketplace value, so two version fields can only drift — the marketplace entry becomes dead weight.

The canonical version is in plugin.json. The marketplace entry carries no version key.

Bump magnitude

The plugin is the versioned unit. Its public API is the aggregate of every skill and hook it ships, plus their documented triggers and behavior. A backward-incompatible change to one skill is therefore a major change to the whole plugin — regardless of diff size.

Determine the bump by backward compatibility, not by change size:

Change to the plugin	Bump
Backward-compatible bug fix — typo, clarification, or correcting a skill to match its already-documented behavior	patch
Backward-compatible addition — a new skill or hook, a new capability in an existing skill, or a trigger broadened to fire in strictly more cases	minor
Backward-incompatible change — an existing skill's behavior or guidance changes the outcome for anyone who relied on the prior version; a trigger narrowed so it no longer fires where it used to; a skill or hook removed or renamed; the plugin renamed or split	major

A large additive rewrite that still does everything the prior version did is minor. A one-line guidance reversal that breaks prior reliance is major.

Post-merge install command

After merge, consuming repos refresh with:

claude plugin install <name>@<marketplace> --scope project

Derive <name> from the plugin's directory name. Derive <marketplace> from the name field in the root .claude-plugin/marketplace.json of this repo. Surface the command verbatim in the PR description. Which repos consume the plugin is the author's knowledge — this skill cannot discover external consumers.

Checklist

Emit this on trigger and verify each item before committing:

Plugin semver checklist:
- [ ] the plugin's .claude-plugin/plugin.json `version` bumped
- [ ] Bump magnitude matches the change (see table above)
- [ ] No `version` field added to the plugin's marketplace.json entry
- [ ] PR description includes the post-merge install command