Detailed Analysis
Claude Code's plugin system now includes a formal mechanism for constraining dependency versions, allowing plugin authors to declare semver ranges that pin upstream plugins to tested, stable versions rather than perpetually tracking the latest release. The feature is configured through the `dependencies` array in a plugin's `.claude-plugin/plugin.json` manifest, where each entry can be either a bare plugin name — which defaults to the latest available version — or a structured object specifying a `name`, a `version` range (using Node.js semver syntax such as `~2.1.0` or `^2.0`), and optionally a `marketplace` field for cross-marketplace resolution. When a plugin with constrained dependencies is installed, Claude Code automatically resolves and installs matching versions, and it re-resolves missing dependencies during `/reload-plugins` or the background auto-update cycle, provided the relevant marketplace is already configured.
The practical motivation for this feature is illustrated through a representative scenario: a `deploy-kit` plugin maintained by one team depends on a `secrets-vault` plugin maintained by another. Without version constraints, an upstream release that renames or removes an MCP tool can silently break dependent plugins across every engineer's environment the moment auto-update runs. The constrained approach — declaring `~2.1.0` — ensures all users of `deploy-kit` stay on the highest matching `2.1.x` patch release until the `deploy-kit` authors explicitly publish a new version with a broader range. This decouples the release cadences of interdependent plugin teams, a critical property in enterprise or multi-team environments where coordination overhead is high and breaking changes are costly.
Version resolution itself is grounded in git tags on the marketplace repository, using a naming convention of `{plugin-name}--v{version}`, such as `secrets-vault--v2.1.0`. The double-hyphen-v separator is deliberately chosen to correctly parse plugin names that themselves contain hyphens, and the prefix-matching approach allows a single repository to host multiple plugins with independent version lines. When multiple installed plugins constrain the same dependency, Claude Code intersects their declared ranges and resolves to the highest version satisfying all constraints simultaneously — a standard dependency resolution strategy borrowed from package managers like npm. If no tag satisfies the intersection, the dependent plugin is disabled with a diagnostic error listing available versions, favoring explicit failure over silent mismatches.
Cross-marketplace dependencies introduce an additional governance layer. By default, Claude Code blocks a plugin from automatically pulling in dependencies from a marketplace other than its own, preventing one marketplace from implicitly expanding a user's trusted plugin surface. The root marketplace's `marketplace.json` can opt into specific external marketplaces via the `allowCrossMarketplaceDependenciesOn` field, and critically, only the root marketplace's allowlist is consulted — trust does not chain through intermediate marketplaces. This design reflects a broader architectural principle in Claude Code's plugin system: explicit, auditable trust boundaries rather than transitive or ambient trust, which is particularly relevant as plugin ecosystems scale and the risk of supply-chain-style dependency manipulation increases.
The timing of this feature lands at a moment when AI coding assistant plugin ecosystems are rapidly maturing from experimental extensions into production infrastructure components. GitHub issues and community discussions as of early 2026 indicate that plugin versioning and engine compatibility constraints had been longstanding gaps, with developers relying on workarounds such as self-contained skills, runtime documentation references, and CLI flags like `--bare` to manage compatibility. The introduction of formal semver-range dependency declarations brings Claude Code's plugin model into alignment with established package management conventions, reducing the operational friction of maintaining stable multi-plugin configurations and positioning the ecosystem for more reliable enterprise adoption.
Read original article →