How the version Field in .claude-plugin/plugin.json Controls Claude Code Updates

The version field in .claude-plugin/plugin.json is the sole signal that Claude Code uses to detect plugin updates; if this string remains unchanged, claude plugin update skips the download even when underlying files have been modified.

The jakubkrehel/skills repository implements a strict versioning contract that governs how Claude Code plugins propagate changes to end users. Understanding exactly how the version field in .claude-plugin/plugin.json affects Claude Code updates prevents silent update failures and ensures users always receive the latest skill definitions.

How Claude Code Compares Version Strings

When a user executes claude plugin update, the client locates the plugin by its name field (in this repository, "interfaces") and reads the version string from .claude-plugin/plugin.json. The runtime compares this value against the version recorded in the local cache. According to the source documentation in AGENTS.md, this field "is the only signal plugin users update on"—the client performs no file-hash verification or timestamp comparison.

If the version string matches the cached record, Claude Code reports "already at the latest version" and terminates without writing to the filesystem. This occurs even when files under the skills/ directory have been edited, committed, and pushed to the repository.

The Update Trigger Mechanism

When the version value increases, Claude Code treats the plugin as stale and initiates a fresh pull. The update sequence validates the new package using the recommended commands before installation:

claude plugin validate .
claude plugin validate .claude-plugin/plugin.json

This validation ensures that the manifest structure, author metadata, and repository links remain compliant with the marketplace requirements defined in the companion file.

Required Update Workflow for Plugin Developers

To successfully ship changes to users, developers must follow a strict three-step workflow after modifying any content in the skills/ directory:

1. Edit skill files under the skills/ directory.
2. Increment the version field in .claude-plugin/plugin.json following semantic versioning practices.
3. Commit both changes together in a single commit (the repository policy requires the version bump to accompany the file modifications).

Example version bump in .claude-plugin/plugin.json:

{
  "name": "interfaces",
  "description": "Skills for building great product interfaces: typography, colors, layout, accessibility, UI polish and writing.",
  "version": "1.6.4",
  "author": {
    "name": "Jakub Krehel",
    "email": "jakub@kbo.sk"
  },
  "homepage": "https://interfaces.dev/",
  "repository": "https://github.com/jakubkrehel/skills",
  "license": "MIT"
}

Failure to increment the version means the claude plugin update command will never trigger a download, rendering the committed changes invisible to users.

Synchronizing Marketplace Metadata

The repository maintains a second manifest at .claude-plugin/marketplace.json that drives the Claude Code marketplace interface. This file must stay in sync with .claude-plugin/plugin.json; when you bump the version in the primary manifest, you must apply the same change to the marketplace manifest to prevent version-mismatch errors during installation.

Summary

• .claude-plugin/plugin.json contains the authoritative version string that Claude Code monitors for updates.
• The claude plugin update command compares this version against the local cache exclusively; it does not inspect file contents or git history.
• If the version remains unchanged, the client skips the update entirely, even when the skills/ directory contains newer code.
• Developers must bump the version and commit it alongside any skill modifications to ensure propagation.
• Validation via claude plugin validate ensures manifest integrity before users receive the update.

Frequently Asked Questions

What happens if I update skill files but forget to bump the version?

Users running claude plugin update will see a message indicating they are already at the latest version and will not receive the modified files. The changes remain in the repository but never propagate to the client's local plugin cache because Claude Code detects no version difference.

Does the marketplace.json version need to match plugin.json?

Yes, the version field in .claude-plugin/marketplace.json must remain synchronized with .claude-plugin/plugin.json. The marketplace manifest provides metadata for the Claude Code plugin browser, and version mismatches can cause installation errors or confusion in the marketplace interface.

How do I validate my plugin before publishing an update?

Run claude plugin validate . from the repository root or claude plugin validate .claude-plugin/plugin.json to verify that your manifest structure, version strings, and repository references meet the requirements. This validation occurs automatically during the update process, but pre-validation catches errors before users attempt installation.

Why does Claude Code use only the version string instead of file hashes?

According to AGENTS.md, the design intentionally uses a single version field as the "sole signal" to simplify both the publishing workflow and client-side logic. This tight coupling makes version management the single point of truth, reducing complexity for both plugin authors and the Claude Code runtime while ensuring deterministic update behavior.

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