New skill: version-bump for Python packages and Claude plugins

[krisrowe]

Problem

No skill in this marketplace (or related ones) covers version-bump
mechanics for Python packages or Claude plugins. The result is that
every repo reinvents the rule independently, often inconsistently,
and some repos miss it entirely — shipping commits without bumping
the version, leaving downstream pip install --upgrade and
pipx install --upgrade blind to the change.

The same pattern recurs across many Python frameworks and apps:

• Single source of truth: __version__ in <package>/__init__.py.
• pyproject.toml mirrors it.
• Bump in the same commit as the change; runtime-touching changes
  must bump.
• Tag with a v prefix (e.g., v0.3.0).
• Push commits and tags together.

Claude plugins follow a structurally similar pattern but with
shape differences:

• Version field lives in .claude-plugin/plugin.json, not
  pyproject.toml, and there is no __version__ Python module
  attribute.
• Releases may include a marketplace-ref update step after the tag.

The bump workflow is identical in spirit (bump → commit → tag →
push) but the files and fields to touch differ by repo shape.
Agents that bump versions for users today either hardcode one
shape, ask for the shape every time, or miss the bump entirely.

Proposed Skill

A version-bump skill that:

1. Detects repo shape from the working tree:

   • Python package: pyproject.toml present, <pkg>/__init__.py
     declares __version__.
   • Claude plugin: .claude-plugin/plugin.json present.
   • Repos that are both (a Python package distributed as a
     plugin) bump both fields together.

2. Verifies CONTRIBUTING has a Version Management section.
   If missing, refuses to bump and offers to insert a templated
   section first. Template should cover: source-of-truth file,
   semver bump table (patch/minor/major), tag format, release
   workflow commands. This is the self-documenting contract — any
   repo the skill operates on ends up with the rule documented in
   the repo itself.

3. Applies the bump to the right files for the detected shape:

   • Python package: edit <pkg>/__init__.py __version__ and
     pyproject.toml [project] version together.
   • Claude plugin: edit .claude-plugin/plugin.json version.
   • Both: edit all three.

4. Bump-with-change is the default. The skill's default mode
   is to stage the version files alongside the user's other
   changes and let the existing commit flow include them in one
   commit. The commit message describes the actual change — no
   chore: prefix, no Conventional Commits ceremony, because no
   semantic-release / python-semantic-release /
   release-please automation is in use across these repos.

5. Catch-up bump is the exception path. When a runtime-touching
   change has already been committed (or pushed) without a bump,
   the skill creates a small follow-up commit titled
   Bump version to X.Y.Z whose body briefly notes what
   unreleased changes the bump covers.

6. Tags annotated (git tag -a vX.Y.Z -m "vX.Y.Z"). User
   pushes — the skill never pushes itself.

Boundary with safe-commit

safe-commit lives in the public claude-coding plugin (a separate
public repo from this marketplace) and gates commits and pushes
behind a privacy/credentials scan. version-bump operates one
rung up: deciding what version this commit should ship as and
ensuring the right files move together. The two are
complementary, not competing — but their pre-commit / pre-push
behavior could conflict if both try to control the commit moment.

This needs careful design before the skill ships. Open questions:

• Does version-bump fire before, after, or alongside
  safe-commit? The natural answer is "before" — bump the
  version files, then safe-commit stages and scans the result
  as one logical commit. But this requires the user (or another
  skill) to invoke version-bump first, which means it cannot be
  enforced.
• Can the two skills be invoked transparently from each other?
  Cross-marketplace dependencies are fragile (the other skill may
  not be installed). Per skill-author guidelines, references
  across skill boundaries should be hint-level, not hard
  dependencies. Each skill must work standalone.
• Whose pre-commit behavior wins on a frontmatter trigger
  conflict? If both skills declare "use before committing
  Python code," the agent picks one — non-deterministic. The
  trigger phrasing for version-bump must be narrow enough that
  it doesn't fire on every commit (only on runtime-touching
  changes the user is about to push), to avoid stepping on
  safe-commit's broader role.
• What is the right composition story? Possibilities:
  (a) version-bump runs only when the user explicitly invokes
  it; (b) version-bump's frontmatter triggers it for explicit
  user intent ("bump version", "release") but not for routine
  commits; (c) version-bump cooperates with safe-commit via a
  documented hand-off in both skills' descriptions.

A separate design pass is warranted before implementation. Do not
build this skill in a way that re-implements pre-commit
intercept logic that competes with safe-commit — that path leads
to unpredictable agent behavior depending on which skill matches
the user's phrasing first.

Design notes from the proposing session

• The split between chore: bump version to X.Y.Z ceremony and a
  plain Bump version to X.Y.Z commit is real and worth being
  explicit about. chore: exists to feed Conventional Commits
  parsers (semantic-release, release-please,
  conventional-changelog). When no such tool is configured, the
  prefix is decoration. The skill should not enforce
  chore: and should explicitly call out that the prefix is only
  appropriate when the repo runs a Conventional Commits-aware
  release tool. Detect via presence of .releaserc*,
  release.config.*, python-semantic-release configuration in
  pyproject.toml, or a release workflow under .github/workflows/.
• The "bump in the same commit as the change" rule is preferable
  to a "separate chore: bump commit" rule because it keeps
  history honest (every commit is exactly one logical change,
  with the version that ships that change) and avoids cluttering
  history with bump-only commits.
• The CONTRIBUTING template the skill should insert needs at
  minimum: source-of-truth files, semver bump table, catch-up
  bump rule, tag format, and the release workflow commands.
• Not every change requires a bump. Documentation-only changes,
  internal refactors that don't touch runtime behavior, and CI
  changes are typical exceptions. The skill should ask, not
  assume.

Work breakdown

• Pick a final home directory under this repo (likely
  coding/version-bump/).
• Resolve the boundary-with-safe-commit design questions
  above before writing the skill body. Document the chosen
  composition strategy in the skill itself.
• Write the SKILL.md frontmatter:
  - Description starting with imperative "Use when..." and
  synonym coverage for "bump version", "release", "tag",
  "publish version", "ship".
  - Trigger phrasing narrow enough not to compete with
  safe-commit on routine commits.
• Write detection logic for repo shape (Python package,
  Claude plugin, both) entirely in the skill body — no
  bundled scripts.
• Write the CONTRIBUTING template the skill inserts when the
  Version Management section is missing.
• Write the bump-with-change default flow.
• Write the catch-up bump exception flow.
• Write the Conventional Commits / semantic-release
  detection logic (only enable chore: prefix when one of
  those tools is configured).
• Document the boundary with safe-commit in the skill body
  so a user who has both installed sees the correct
  composition story.
• Add hint-level cross-references in the
  authoring/operating skills that mention version bumps
  (e.g., author-mcp-app, any gapp authoring skill, any
  plugin-authoring skill) — pointing at this skill but not
  depending on it.
• Capture in this repo's CONTRIBUTING the policy that
  versioning skills must not duplicate or compete with
  pre-commit safety skills installed from other
  marketplaces.
• Tests: at minimum, a fixture-based test that the skill's
  detection logic correctly identifies each repo shape.