Claude Plugin Manifest Versioning Explained: How Semantic Versioning Works

Claude plugins use a per-plugin versioning system based on semantic versioning (semver) stored in a version field inside .claude-plugin/plugin.json manifests.

The anthropics/claude-plugins-community repository implements a decentralized versioning model where each plugin maintains its own version independently. This approach enables the Claude marketplace and plugin loader to track releases, enforce compatibility, and support deterministic deployments.

How Plugin Manifest Versioning Works

Every Claude plugin ships with a manifest file located at .claude-plugin/plugin.json. This JSON file contains essential metadata, with the "version" field serving as the canonical version identifier. The versioning system follows semantic versioning conventions, using strings like "1.12.1" or "0.8.0".

The version field powers three critical functions:

• Update detection — The marketplace compares installed versions against repository versions to flag available updates
• Runtime compatibility — The plugin loader validates that a plugin's version meets minimum requirements for the current Claude Code runtime
• Deterministic deployments — CI pipelines and user environments can pin to specific versions or automate upgrade logic

Because each plugin carries its own manifest, version tracking is per-plugin rather than repository-wide. No global version file governs the entire claude-plugins-community collection.

Manifest Schema and Required Fields

The manifest schema is informal but consistent across plugins in the repository. Required and common fields include:

Field	Purpose	Example
name	Plugin identifier	"TRES Finance"
description	Human-readable summary	"Query on-chain treasury data"
version	Semver release tag	"1.12.1"
repository	Source code URL	https://github.com/...
settings	Optional configuration schema	{...}

The version field is mandatory for marketplace indexing. Without it, the plugin will not be discoverable or installable through official channels.

Real-World Version Examples in the Repository

The claude-plugins-community repository demonstrates this versioning pattern across multiple plugins:

Plugin	Manifest Path	Current Version
TRES Finance	tres-finance-plugin/.claude-plugin/plugin.json	"1.12.1"
TestDino	testdino/.claude-plugin/plugin.json	"1.0.0"
QuickDesign	quickdesign/.claude-plugin/plugin.json	"0.8.0"
Eli5	eli5/.claude-plugin/plugin.json	"1.0.0"

These manifests are plain JSON files, making version bumps straightforward: developers edit the version field, commit the change, and the marketplace reflects the update automatically.

Programmatically Reading and Validating Versions

Because manifests are standard JSON, you can integrate version checks into build pipelines, deployment scripts, or validation tools.

Python: Extract Plugin Version

import json
import pathlib

def get_plugin_version(plugin_dir: pathlib.Path) -> str:
    """Read the version field from a Claude plugin manifest."""
    manifest_path = plugin_dir / ".claude-plugin" / "plugin.json"
    with manifest_path.open() as f:
        data = json.load(f)
    return data["version"]

# Example usage

print(get_plugin_version(pathlib.Path("tres-finance-plugin")))

# Output: 1.12.1

Bash: Version Compatibility Check

#!/usr/bin/env bash
manifest=".claude-plugin/plugin.json"

if [[ -f $manifest ]]; then
    version=$(jq -r .version "$manifest")
    echo "Plugin version: $version"
    
    # Reject pre-1.0 releases in production deployments

    if [[ "$(printf '%s\n' "$version" "1.0.0" | sort -V | head -n1)" != "1.0.0" ]]; then
        echo "Version $version is older than 1.0.0 — aborting deployment."
        exit 1
    fi
fi

Both examples operate directly on the .claude-plugin/plugin.json file path, matching the structure used throughout the repository.

Version Update Workflows

Plugin developers manage versions through standard release practices:

1. Manual updates — Edit version in the manifest before committing a release
2. Automated updates — Use release scripts or CI pipelines to bump semver based on commit conventions
3. Marketplace synchronization — Committed manifest changes are automatically indexed

No additional registration step is required. The presence of a valid version string in the canonical manifest location is sufficient for the ecosystem to recognize and distribute the plugin.

Summary

• Claude plugin manifests use per-plugin semantic versioning stored in .claude-plugin/plugin.json
• The version field is required and follows semver conventions
• Version data enables update detection, runtime compatibility checks, and deterministic deployments
• The claude-plugins-community repository contains multiple working examples, including TRES Finance at version 1.12.1
• Manifests are plain JSON, making version extraction and validation trivial in any language

Frequently Asked Questions

What happens if a plugin manifest is missing the version field?

The Claude marketplace will not index the plugin, rendering it undiscoverable and uninstallable through official channels. The plugin loader may also reject manifests without a valid version string during manual installation.

Can I use non-semver version formats like "v1.0" or "2024.06"?

While the manifest schema does not strictly enforce semver parsing, the marketplace and loader expect semantic versioning. Deviating from MAJOR.MINOR.PATCH format may cause compatibility check failures or sorting errors when comparing versions.

How does the marketplace detect when a plugin needs updating?

The marketplace compares the installed plugin's version field against the latest commit in the repository's corresponding .claude-plugin/plugin.json path. When the version strings differ, the newer version is flagged as available for installation.

Is there a way to specify minimum Claude Code runtime versions?

The base manifest schema in claude-plugins-community does not include a runtime version constraint field. Compatibility is currently handled implicitly through marketplace curation and loader validation rather than explicit minimum-version declarations in the manifest.

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