# How PM Skills Handles Versioning and Release Management for Claude Plugins

> Discover how PM Skills manages versioning and releases for Claude plugins using a dual-level system, Git tags, and GitHub Actions for automated pipelines.

- Repository: [Pawel Huryn/pm-skills](https://github.com/phuryn/pm-skills)
- Tags: best-practices
- Published: 2026-07-10

---

**PM Skills implements a dual-level versioning system where global releases are tracked in [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) while individual plugins maintain independent versions in their respective [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main//.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.

```json
// .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`](https://github.com/phuryn/pm-skills/blob/main/.claude-plugin/plugin.json) with a discrete `"version"` entry. For example, [`pm-execution/.claude-plugin/plugin.json`](https://github.com/phuryn/pm-skills/blob/main/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.

```json
// 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`](https://github.com/phuryn/pm-skills/blob/main/.github/workflows/tag-on-merge.yml) executes on every push to `main`. It parses [`marketplace.json`](https://github.com/phuryn/pm-skills/blob/main/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.

```yaml

# .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`](https://github.com/phuryn/pm-skills/blob/main//.claude-plugin/marketplace.json) to increment the global version and update any affected plugin's local [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main//.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`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) version to provide immutable release markers.
- **Fully automated pipeline**: The [`.github/workflows/tag-on-merge.yml`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main//.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`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) or a plugin's [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/plugin.json). The [`.github/workflows/tag-on-merge.yml`](https://github.com/phuryn/pm-skills/blob/main/.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`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) tracks the global suite version for the Claude Marketplace listing, each plugin maintains its own semantic version in its local [`plugin.json`](https://github.com/phuryn/pm-skills/blob/main/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`](https://github.com/phuryn/pm-skills/blob/main/marketplace.json) and serve as the source of truth for the CI system when generating release artifacts and publishing to the Claude Marketplace.