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

The Claude Plugins Community repository automates plugin versioning and updates through Semantic Versioning declared in individual plugin.json files, aggregated into a central 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 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:

{
  "version": "0.8.0"
}

This value is located at 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 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. 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. 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. 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 points to a valid, existing plugin directory
• Version Synchronization – Verifies that the version field in marketplace.json matches the corresponding value in the plugin’s local 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. This daily sweep detects when upstream repositories have advanced beyond the SHAs recorded in 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 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:

claude plugin validate ./my-plugin

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

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:

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, as documented in README.md.

Summary

• Plugin versions are declared in .claude-plugin/plugin.json using Semantic Versioning and manually maintained by authors
• Centralized state is stored in /.claude-plugin/marketplace.json, which serves as the marketplace source of truth
• Continuous validation runs via .github/workflows/validate-plugins.yml to check version alignment and security on every push
• Daily synchronization occurs through .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 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 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. The repository’s internal pipeline will sync this change to 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. 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.

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