# How Plugin Versioning and Updates Work in the Claude Plugins Community Repository

> Learn how Claude Plugins Community automates versioning and updates using Semantic Versioning and GitHub Actions. Discover the process for plugin management.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: how-to-guide
- Published: 2026-09-13

---

**The Claude Plugins Community repository automates plugin versioning and updates through Semantic Versioning declared in individual [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json) files, aggregated into a central [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json), and synchronized via daily GitHub Actions that validate changes and open isolated pull requests for each upstream modification.**

The `anthropics/claude-plugins-community` repository implements a rigorous, automated pipeline to manage plugin versioning and updates across its entire ecosystem. This system ensures that version numbers remain accurate, upstream changes propagate safely, and the Claude marketplace always reflects the current state of every community plugin without requiring manual synchronization.

## Semantic Versioning in plugin.json

Every plugin in the repository declares its version locally within its own manifest file. The `version` field in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) follows strict **Semantic Versioning (semver)** standards, allowing automated tools and users to understand the impact of each release.

For example, the QuickDesign plugin specifies its version as:

```json
{
  "version": "0.8.0"
}

```

This value is located at [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json). Plugin authors manually increment this field when releasing new features, bug fixes, or breaking changes, ensuring that the version accurately reflects the semantic meaning of the modification according to [semver.org](https://semver.org/) specifications.

## The Central marketplace.json Manifest

While individual plugins maintain their own version metadata, the repository aggregates all plugin data into a single source of truth at [`/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main//.claude-plugin/marketplace.json). This central manifest powers the Claude Code and Cowork marketplaces, containing both the **version** and **Git SHA** for every plugin entry.

The marketplace file mirrors the version declared in each plugin’s local [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json). This dual-layer architecture ensures that the marketplace can be consumed as a single file while maintaining clear ownership of version data within each plugin directory.

## Automated Validation with CI Workflows

The repository enforces version consistency and security through continuous integration defined in [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml). This workflow triggers on every push to validate the entire plugin ecosystem.

The **Validate Plugins** workflow performs three critical checks:

- **Directory Validation** – Confirms every entry in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) points to a valid, existing plugin directory
- **Version Synchronization** – Verifies that the `version` field in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) matches the corresponding value in the plugin’s local [`plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/plugin.json)
- **Security Scanning** – Runs internal security scans against each plugin to ensure compliance with repository standards

## Daily Upstream Synchronization via bump-plugin-shas

To keep external plugins current without manual intervention, the repository runs a scheduled GitHub Action defined in [`.github/workflows/bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/bump-plugin-shas.yml). This daily sweep detects when upstream repositories have advanced beyond the SHAs recorded in [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json).

When the workflow identifies a stale SHA, it executes the following automated sequence:

1. **Validation** – Runs `claude plugin validate` against the new upstream commit to ensure compatibility
2. **Branch Creation** – Opens a dedicated pull request on a branch named `bump/<plugin-name>`
3. **CI Dispatch** – Automatically triggers the **Validate Plugins** workflow on the new branch to confirm the change passes all checks before human review

Because each plugin receives its own isolated PR, a failure in one upstream repository cannot block updates for other plugins in the marketplace.

## The Freeze List for Broken Upstream Commits

Not all upstream changes are safe to propagate. The repository maintains a freeze list at [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt) that contains known-broken upstream commits. The **bump-plugin-shas** workflow consults this file during its daily sweep and ignores any SHAs listed there.

This mechanism protects the marketplace from repeatedly attempting to integrate failing commits, ensuring that transient upstream breakages do not spam the repository with failing pull requests or interrupt the synchronization of healthy plugins.

## Practical Commands for Plugin Management

Developers and maintainers can interact with the versioning system directly using the Claude CLI. To verify a plugin locally before submission:

```bash
claude plugin validate ./my-plugin

```

To manually bump an external plugin’s SHA (typically executed by CI, but available for local testing):

```bash
claude plugin bump \
  --marketplace .claude-plugin/marketplace.json \
  --plugin-name my-external-plugin \
  --new-sha $(git rev-parse HEAD)

```

To inspect the current version of any plugin programmatically:

```bash
jq '.version' quickdesign/.claude-plugin/plugin.json

# Returns: "0.8.0"

```

## Community Contribution Policy

Direct pull requests to the repository are automatically closed by automation. All changes must flow through Anthropic’s internal review pipeline, which updates the marketplace nightly. Contributors wishing to add or modify plugins must submit through the official portal at [clau.de/plugin-directory-submission](https://clau.de/plugin-directory-submission), as documented in [`README.md`](https://github.com/anthropics/claude-plugins-community/blob/main/README.md).

## Summary

- **Plugin versions** are declared in [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) using Semantic Versioning and manually maintained by authors
- **Centralized state** is stored in [`/.claude-plugin/marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main//.claude-plugin/marketplace.json), which serves as the marketplace source of truth
- **Continuous validation** runs via [`.github/workflows/validate-plugins.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/validate-plugins.yml) to check version alignment and security on every push
- **Daily synchronization** occurs through [`.github/workflows/bump-plugin-shas.yml`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/workflows/bump-plugin-shas.yml), which creates isolated PRs for upstream SHA updates
- **Failure isolation** is achieved through per-plugin branches (`bump/<plugin-name>`) and the [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt) freeze list
- **Submissions** must go through the official portal; direct PRs are rejected automatically

## Frequently Asked Questions

### How do I update my plugin's version in the marketplace?

Update the `version` field in your plugin’s [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.claude-plugin/plugin.json) following Semantic Versioning standards (e.g., incrementing from `"0.8.0"` to `"0.9.0"` for new features). Submit this change through the official submission portal at [clau.de/plugin-directory-submission](https://clau.de/plugin-directory-submission). The repository’s internal pipeline will sync this change to [`marketplace.json`](https://github.com/anthropics/claude-plugins-community/blob/main/marketplace.json) during the next nightly update.

### What happens if my upstream repository has a broken commit?

If an upstream commit fails validation during the daily bump sweep, it can be added to [`.github/freeze-shas.txt`](https://github.com/anthropics/claude-plugins-community/blob/main/.github/freeze-shas.txt). This prevents the **bump-plugin-shas** workflow from attempting to integrate that specific SHA, protecting the marketplace from repeated build failures while you fix the issue upstream.

### Can I submit a pull request directly to this repository?

No. Direct pull requests to the `anthropics/claude-plugins-community` repository are automatically closed by repository automation. All version updates and new plugin submissions must be processed through the official submission portal, which feeds into Anthropic’s internal review pipeline before merging.

### How often does the marketplace check for new upstream versions?

The **bump-plugin-shas** workflow runs on a daily schedule, inspecting every external plugin entry to detect moved upstream SHAs. When changes are found, the system validates them and opens per-plugin pull requests immediately, ensuring the marketplace typically reflects upstream changes within 24 hours of publication.