[DOCS] Plugin dependency docs missing git-tag version constraint update behavior
Documentation Type
Missing documentation (feature not documented)
Documentation Location
https://code.claude.com/docs/en/plugins-reference
Section/Topic
plugin.json manifest schema, plugin dependency/version resolution behavior, and plugin auto-update behavior for git-tagged dependencies
Current Documentation
The plugin reference currently says it documents the manifest fields comprehensively, but it does not describe plugin-to-plugin dependency declarations or version-constraint behavior:
The.claude-plugin/plugin.jsonfile defines your plugin's metadata and configuration. This section documents all supported fields and options. ``json { "name": "plugin-name", "version": "1.2.0", "description": "Brief plugin description", ... "monitors": "./monitors.json" }``
The marketplace guide documents only fixed git pins for plugin sources:
You can pin to a specific branch, tag, or commit: ``json { "name": "github-plugin", "source": { "source": "github", "repo": "owner/plugin-repo", "ref": "v2.0.0", "sha": "a1b2c3d4e5f6a7b8c9d0e1f2a3b4c5d6e7f8a9b0" } }`ref: Optional. Git branch or tag (defaults to repository default branch)sha`: Optional. Full 40-character git commit SHA to pin to an exact version
The install/update docs only describe generic latest-version updates:
Claude Code can automatically update marketplaces and their installed plugins at startup. When auto-update is enabled for a marketplace, Claude Code refreshes the marketplace data and updates installed plugins to their latest versions.
Update a plugin to the latest version.
What's Wrong or Missing?
Changelog v2.1.119 added a user-visible behavior change: plugins pinned by another plugin's version constraint now auto-update to the highest satisfying git tag.
The current docs do not explain:
A. How plugin dependency version constraints are declared
plugins-reference says it documents all supported plugin.json fields, but there is no documented field or schema explanation for one plugin depending on another plugin with a version constraint.
B. How constraint resolution works for git-based plugins
plugin-marketplaces explains fixed ref and sha pins, but not semver-like dependency constraints that resolve against git tags.
C. How auto-update behaves when a dependency is constraint-pinned
discover-plugins and plugins-reference say plugins update to the “latest version,” but they do not explain that dependency-constrained git plugins advance to the highest satisfying tag rather than staying on the originally installed tag.
Without this, plugin authors and admins cannot reliably predict how dependent plugins are selected or updated.
Suggested Improvement
Add a dedicated subsection to plugins-reference for plugin dependencies/version constraints that covers:
- The manifest field(s) used to declare that one plugin depends on another
- Accepted version-constraint syntax
- How git-based dependencies resolve against tags
- The v2.1.119 behavior that auto-update selects the highest satisfying git tag for dependency-constrained plugins
- How this differs from fixed
refandshapinning
Then add short cross-references:
- In
plugin-marketplaces, note that direct plugin sourceref/shapinning is different from dependency-based version resolution - In
discover-plugins, link the auto-update section to the detailed dependency/version-resolution reference
An example would help clarify expected behavior for a dependency constrained to a range such as ^2.0.0 and what tag Claude Code selects during auto-update.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/plugins-reference | plugin.json schema claims to document all supported fields; claude plugin update is described here |
| https://code.claude.com/docs/en/plugin-marketplaces | Documents git plugin source ref/sha pinning and version resolution |
| https://code.claude.com/docs/en/discover-plugins | Documents marketplace/plugin auto-update behavior at startup |
Total scope: 3 pages affected
Source: Changelog v2.1.119
Exact changelog entry: Plugins pinned by another plugin's version constraint now auto-update to the highest satisfying git tag
3 Comments
Found 3 possible duplicate issues:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
Issue #52608 Verification
Title: [DOCS] Plugin dependency docs missing git-tag version constraint update behavior
Issue Date: 2026-04-23
Verification Date: 2026-04-28
Status: RESOLVED
---
Issue Summary
This issue reports that Claude Code's plugin documentation did not explain how plugin dependencies are declared in
plugin.json, how version constraints resolve against git tags, and how auto-update behaves for dependency-constrained plugins.---
Verification Results
Claim 1: The docs did not explain how plugin dependency version constraints are declared
Status: RESOLVED
At https://code.claude.com/docs/en/plugins-reference, lines 437-437, the manifest schema now documents the field directly: "
dependencies| array | Other plugins this plugin requires, optionally with semver version constraints. See Constrain plugin dependency versions".At https://code.claude.com/docs/en/plugin-dependencies, lines 27-29, the dedicated page now states: "List dependencies in the
dependenciesarray of your plugin's.claude-plugin/plugin.json. Each entry is either a plugin name or an object with a version constraint." Lines 46-52 then document the supported object fields and version syntax.Verdict: The current docs now document both the
dependenciesmanifest field and the syntax used to declare version-constrained dependencies.---
Claim 2: The docs did not explain how git-based dependency version constraints resolve
Status: RESOLVED
At https://code.claude.com/docs/en/plugin-dependencies, lines 83-85, the docs now state: "Version constraints resolve against git tags on the marketplace repository." and "Tag each release as
{plugin-name}--v{version}".At the same page, lines 95-97 explain the resolution behavior: "Claude Code lists the marketplace's tags, filters to those starting with
secrets-vault--v, and fetches the highest version satisfying~2.1.0." The page also explains that the resolved tag semver is recorded separately fromplugin.json'sversion.At https://code.claude.com/docs/en/plugin-marketplaces, lines 792-794, the marketplace docs now cross-reference this behavior: "A plugin can constrain its dependencies to a semver range... See Constrain plugin dependency versions for the
{plugin-name}--v{version}git-tag convention, range syntax, and how multiple constraints on the same dependency are combined."Verdict: The current docs now describe git-tag-based resolution and distinguish dependency-based version resolution from simple source pinning.
---
Claim 3: The docs did not explain auto-update behavior for dependency-constrained plugins
Status: RESOLVED
At https://code.claude.com/docs/en/plugin-dependencies, lines 105-113, the docs explain how multiple constraints are combined and then state: "Auto-update fetches a constrained dependency at the highest git tag that satisfies every installed plugin's range, rather than at the marketplace's latest version, so the dependency continues to receive updates within its allowed range."
At https://code.claude.com/docs/en/plugin-dependencies, lines 111-115, the table and follow-up text also clarify constrained update behavior, including: "The dependency stays at
2.1.0. Auto-update skips newer versions while plugin A is installed" and "When you uninstall the last plugin that constrains a dependency, the dependency is no longer held and resumes tracking its marketplace entry on the next update."Verdict: The current docs now explicitly document the auto-update behavior that the issue reported as missing.
---
Current State
| Claim | Status |
|-------|--------|
| Dependency declarations in
plugin.jsonwere undocumented | RESOLVED || Git-tag version constraint resolution was undocumented | RESOLVED |
| Auto-update behavior for constrained dependencies was undocumented | RESOLVED |
---
Suggested Fix
N/A - issue has been resolved.
---
References
dependenciesmanifest field and links to the dependency-version guide.---
Conclusion & Recommendation
Primary Concern: The issue reported missing documentation for plugin dependency declarations, git-tag-based version resolution, and constrained auto-update behavior.
Resolution Status: RESOLVED
Recommendation: CLOSE
The current documentation now covers all three reported gaps. The manifest schema, dedicated dependency guide, and marketplace cross-reference together document the version-constraint syntax, git-tag resolution rules, and highest-satisfying-tag auto-update behavior.
---
This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.