# Claude Plugin Manifest Versioning Explained: How Semantic Versioning Works

> Learn how Claude plugin manifests use semantic versioning to manage updates. Understand the version field in plugin.json for effective Claude plugin development.

- Repository: [Anthropic/claude-plugins-community](https://github.com/anthropics/claude-plugins-community)
- Tags: deep-dive
- Published: 2026-09-01

---

**Claude plugins use a per-plugin versioning system based on semantic versioning (semver) stored in a `version` field inside [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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](https://semver.org/) 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`](https://github.com/anthropics/claude-plugins-community/blob/main/tres-finance-plugin/.claude-plugin/plugin.json) | `"1.12.1"` |
| TestDino | [`testdino/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/testdino/.claude-plugin/plugin.json) | `"1.0.0"` |
| QuickDesign | [`quickdesign/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/quickdesign/.claude-plugin/plugin.json) | `"0.8.0"` |
| Eli5 | [`eli5/.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-community/blob/main/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

```python
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

```bash
#!/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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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`](https://github.com/anthropics/claude-plugins-community/blob/main/.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.