How PM Skills Handles Versioning and Release Management for Claude Plugins

PM Skills implements a dual-level versioning system where global releases are tracked in marketplace.json while individual plugins maintain independent versions in their respective plugin.json files, with Git tags and GitHub Actions automating the entire release pipeline.

The phuryn/pm-skills repository demonstrates a sophisticated approach to versioning and release management that balances granular plugin control with coordinated global releases. This open-source project manages a suite of Claude plugins using JSON-based version tracking and CI-driven automation to eliminate manual release overhead while maintaining full traceability.

Understanding the Dual-Level Versioning Strategy

PM Skills treats every plugin as an independent, versioned component while maintaining a single top-level version for the entire collection. This architecture allows specific plugins to evolve independently without forcing unnecessary full-suite releases.

Global Package Version

The global suite version lives in /.claude-plugin/marketplace.json within the "version" field. This value represents the released version of the entire PM Skills suite that appears on the Claude Marketplace. In the current release, this file specifies "2.1.0" as the global version.

// .claude-plugin/marketplace.json
{
  "$schema": "...",
  "name": "pm-skills",
  "version": "2.1.0",
  "description": "Product management skills for Claude"
}

Individual Plugin Versions

Each plugin folder contains its own .claude-plugin/plugin.json with a discrete "version" entry. For example, pm-execution/.claude-plugin/plugin.json maintains its own version string independently of the global release. The Claude runtime reads this version when loading a specific plugin, enabling granular compatibility checks.

// pm-execution/.claude-plugin/plugin.json
{
  "name": "pm-execution",
  "version": "2.1.0",
  "description": "Execution and delivery management"
}

Automated Release Pipeline with Git Tags

The release workflow is driven by Git tags and CI pipelines that automatically publish a new package whenever the main branch receives a version bump. Tags under .git/refs/tags/ (e.g., v2.1.0) serve as immutable source-of-truth markers for the CI system.

The Tag-on-Merge Workflow

The workflow file .github/workflows/tag-on-merge.yml executes on every push to main. It parses marketplace.json to detect version changes and automatically creates a corresponding Git tag. This ensures that version bumps in the JSON files immediately trigger release generation without manual intervention.

# .github/workflows/tag-on-merge.yml (excerpt)

on:
  push:
    branches: [main]

jobs:
  tag:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Create tag
        run: |
          VERSION=$(jq -r .version .claude-plugin/marketplace.json)
          git tag "v${VERSION}"
          git push origin "v${VERSION}"

From Version Bump to Published Release

When the CI workflow detects a version increment, it pushes a matching Git tag to .git/refs/tags/ following the vX.Y.Z format. This tag triggers subsequent jobs that package the plugins, update the Claude Marketplace metadata, and make the new release available to users. The entire process completes automatically once a developer merges a version bump into main.

Step-by-Step Release Process

1. Developer bumps version – Edit /.claude-plugin/marketplace.json to increment the global version and update any affected plugin's local plugin.json file.

2. Commit and merge – Submit the version changes as a pull request and merge into the main branch.

3. CI triggers – The tag-on-merge workflow detects the version change in marketplace.json, creates a new Git tag (e.g., v2.2.0), and pushes it to .git/refs/tags/.

4. Artifact generation – The workflow packages all plugins, synchronizes the Marketplace metadata, and publishes the release, making it immediately available to Claude users.

Summary

• Dual-level versioning: Global suite versions reside in /.claude-plugin/marketplace.json while individual plugin versions live in their respective */.claude-plugin/plugin.json files.
• Git tag source of truth: Release tags follow the vX.Y.Z format in .git/refs/tags/ and mirror the marketplace.json version to provide immutable release markers.
• Fully automated pipeline: The .github/workflows/tag-on-merge.yml workflow eliminates manual release steps by detecting version bumps and automatically creating tags and publishing artifacts.
• Independent plugin evolution: The architecture allows specific plugins to maintain separate version histories while still participating in coordinated global releases.

Frequently Asked Questions

How does PM Skills store version information?

PM Skills stores the global suite version in /.claude-plugin/marketplace.json under the "version" field, while individual plugin versions reside in their respective */.claude-plugin/plugin.json files. For example, pm-execution/.claude-plugin/plugin.json tracks that specific plugin's version independently from the global release displayed on the Claude Marketplace.

What triggers a new release in PM Skills?

A new release triggers when a developer commits a version bump to the main branch in either marketplace.json or a plugin's plugin.json. The .github/workflows/tag-on-merge.yml CI workflow detects this change during the push event, automatically creates a matching Git tag in .git/refs/tags/ (e.g., v2.1.0), and initiates the publication process to the Claude Marketplace.

Can individual plugins be versioned independently?

Yes. While marketplace.json tracks the global suite version for the Claude Marketplace listing, each plugin maintains its own semantic version in its local plugin.json file. This allows specific plugins to receive updates and version increments without requiring a full suite release, though the CI pipeline coordinates both levels during the automated release process to ensure consistency.

Where are the release tags stored?

Release tags are stored as Git references in .git/refs/tags/ following the format vX.Y.Z (e.g., v2.1.0). These tags mirror the version specified in marketplace.json and serve as the source of truth for the CI system when generating release artifacts and publishing to the Claude Marketplace.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}