# Claude Plugin Backwards Compatibility Policy: Semantic Versioning and Migration Guidelines

> Understand the Claude plugin backwards compatibility policy. Learn how semantic versioning ensures stability and when to expect breaking changes with migration guides.

- Repository: [Anthropic/claude-plugins-official](https://github.com/anthropics/claude-plugins-official)
- Tags: policy
- Published: 2026-03-13

---

**Claude plugins follow strict semantic versioning where minor releases must maintain backwards compatibility, major releases may introduce breaking changes requiring migration guides, and patch releases contain only bug fixes.**

The **Claude plugin backwards compatibility policy** governs how developers version and publish extensions for Claude Code in the `anthropics/claude-plugins-official` repository. This framework ensures that end-users receive stable updates while allowing authors to iterate and improve their plugins without disrupting existing workflows.

## Semantic Versioning Structure for Claude Plugins

Claude plugins use **semantic versioning** in the format `MAJOR.MINOR.PATCH`. The policy defines strict compatibility guarantees for each release type, enforced through manifest validation and the publishing workflow.

### Patch Releases (x.y.Z)

**Patch releases** contain no user-visible changes beyond bug fixes or security patches. Authors increment the `PATCH` number while keeping the API and behavior unchanged. These updates require no action from users and automatically replace previous versions without breaking existing functionality.

### Minor Releases (x.Y.0)

**Minor releases** add new features but must remain **backward-compatible** with prior minor versions. According to the marketplace considerations documentation in [`plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md) (lines 28-34), authors increment the `MINOR` version when adding capabilities without removing or altering existing commands, agents, or skills.

### Major Releases (X.0.0)

**Major releases** may introduce **breaking changes** that require user migration. When incrementing the `MAJOR` version, authors must provide a migration guide in the plugin's README and may optionally support the previous major version for a transition period. The plugin loader treats major version bumps as distinct entities, leaving existing installations untouched until users explicitly upgrade.

## Manifest Validation and Version Enforcement

The policy is enforced through strict validation of the [`plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugin.json) manifest file located at [`.claude-plugin/plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/.claude-plugin/plugin.json). The [`plugins/plugin-dev/skills/plugin-structure/SKILL.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/plugin-structure/SKILL.md) file (lines 83-90) defines the required `version` field format, while [`plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md) (lines 85-88) validates that version strings follow semantic versioning.

Invalid version strings, such as those missing the `PATCH` component, cause immediate load errors. This validation prevents accidental breaking changes from reaching users.

```typescript
function isValidVersion(v: string): boolean {
  // Semantic version pattern: X.Y.Z where X,Y,Z are non-negative integers
  return /^\d+\.\d+\.\d+$/.test(v);
}

```

Claude Code runs validation logic similar to the snippet above before accepting any plugin version, ensuring that only properly formatted semantic versions enter the ecosystem.

## How the Plugin Loader Handles Version Updates

The plugin loader in Claude Code parses the `version` field from [`plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugin.json) to determine compatibility handling. When the loader detects a new version of an installed plugin, it applies different strategies based on the release type:

- **Minor or patch bumps**: The loader swaps the old implementation automatically without requiring user migration, as these are guaranteed backward-compatible per the policy defined in [`plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md).

- **Major bumps**: The loader treats the plugin as a distinct entity. Existing installations remain pinned to the previous major version until the user explicitly chooses to upgrade.

### Component Discovery and Additive Changes

Default directories including `commands/`, `agents/`, `skills/`, and `hooks/` are auto-scanned during plugin load. Adding new components in a minor release does not affect existing functionality because discovery is strictly additive. Existing commands and agents continue to work unchanged even as new capabilities are introduced alongside them.

## Implementing Update Notifications

Plugins can expose an **update-aware command** that checks the current installed version against the latest published version. The [`plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md) file (lines 46-63) provides patterns for implementing these notifications, ensuring users are only alerted to backward-compatible updates.

```markdown
---
description: Check for plugin updates
---

# Check for Updates

Current version: 1.2.0
Latest version: {{latest_version}}

{{#if (neq current_version latest_version)}}
📢 **UPDATE AVAILABLE**
- New version: {{latest_version}}
- What's new:
  - {{release_notes}}
{{/if}}

```

When `latest_version` represents a higher minor or patch number, the command displays an update prompt without breaking the user's workflow. This aligns with the semantic versioning guarantees, ensuring users only receive automatic update notifications for compatible improvements.

## Version Bump Examples for Plugin Authors

When preparing a release, update the `version` field in your [`plugin.json`](https://github.com/anthropics/claude-plugins-official/blob/main/plugin.json) according to the change type:

```json
{
  "name": "code-review-assistant",
  "version": "1.2.0",
  "description": "Adds automated linting without breaking existing commands",
  "commands": ["./commands"]
}

```

In this example, the bump from `1.1.0` to `1.2.0` signals a backward-compatible enhancement. For breaking changes, the version would advance to `2.0.0` with accompanying migration documentation in the README.

## Summary

- **Claude plugins use strict semantic versioning** (`MAJOR.MINOR.PATCH`) as defined in [`plugins/plugin-dev/skills/plugin-structure/SKILL.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/plugin-structure/SKILL.md).
- **Patch releases** (`x.y.Z`) contain only bug fixes and security patches with no breaking changes.
- **Minor releases** (`x.Y.0`) must maintain backwards compatibility while adding new features, as enforced by manifest validation in [`plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md).
- **Major releases** (`X.0.0`) may introduce breaking changes and require migration guides; the plugin loader treats these as distinct entities requiring explicit user upgrade.
- **Component discovery** is additive, ensuring new features in minor releases do not disrupt existing commands or agents.

## Frequently Asked Questions

### What happens if I accidentally release a breaking change in a minor version?

The manifest validation system in [`plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md) (lines 85-88) checks version formatting, but semantic meaning relies on author compliance. If you violate the backwards compatibility policy by breaking existing functionality in a minor release, users may experience workflow disruptions. You should immediately issue a patch release reverting the breaking change or accelerate a major version bump with proper migration documentation.

### How does Claude Code handle major version updates differently from minor updates?

For **minor and patch updates**, the plugin loader automatically swaps the implementation without user intervention, trusting the backwards compatibility guarantees. For **major version updates**, the loader treats the new version as a completely distinct plugin entity, leaving existing installations pinned to the previous major version until the user explicitly upgrades through the marketplace or CLI.

### Can I remove or rename existing commands in a minor release?

No. Removing or renaming existing commands constitutes a breaking change that violates the **Claude plugin backwards compatibility policy**. Minor releases must only add capabilities without altering or removing existing ones. All component discovery is additive, meaning new files in `commands/`, `agents/`, `skills/`, or `hooks/` can be added, but existing ones must remain functional and unchanged.

### Where is the version format and backwards compatibility policy documented in the repository?

The version format using semantic versioning is documented in [`plugins/plugin-dev/skills/plugin-structure/SKILL.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/plugin-structure/SKILL.md) (lines 83-90). The backwards compatibility requirements for minor releases are explicitly stated in [`plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/command-development/references/marketplace-considerations.md) (lines 28-34). Manifest validation rules appear in [`plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md`](https://github.com/anthropics/claude-plugins-official/blob/main/plugins/plugin-dev/skills/plugin-structure/references/manifest-reference.md) (lines 85-88).