[DOCS] Plugin docs missing `plugin.json` dependency declarations and auto-install behavior

[coygeek]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

https://code.claude.com/docs/en/plugins-reference

Section/Topic

Plugin manifest schema (.claude-plugin/plugin.json) and plugin installation behavior for dependency plugins

Current Documentation

The manifest reference currently says:

The .claude-plugin/plugin.json file defines your plugin's metadata and configuration. This section documents all supported fields and options.

{
  "name": "plugin-name",
  "version": "1.2.0",
  "description": "Brief plugin description",
  "author": {
    "name": "Author Name",
    "email": "author@example.com",
    "url": "https://github.com/author"
  },
  "homepage": "https://docs.example.com/plugin",
  "repository": "https://github.com/author/plugin",
  "license": "MIT",
  "keywords": ["keyword1", "keyword2"],
  "skills": "./custom/skills/",
  "commands": ["./custom/commands/special.md"],
  "agents": "./custom/agents/",
  "hooks": "./config/hooks.json",
  "mcpServers": "./mcp-config.json",
  "outputStyles": "./styles/",
  "lspServers": "./.lsp.json",
  "monitors": "./monitors.json"
}

The install guide currently says:

Once you've added marketplaces, you can install plugins directly (installs to user scope by default):

/plugin install plugin-name@marketplace-name

To choose a different installation scope, use the interactive UI...

The marketplace guide also says:

Each plugin entry in the plugins array describes a plugin and where to find it. You can include any field from the plugin manifest schema (like description, version, author, commands, hooks, etc.), plus these marketplace-specific fields: source, category, tags, and strict.

None of these pages document plugin dependency declarations in plugin.json, what happens when marketplace entries omit them, or that /plugin install auto-installs and reports dependency plugins.

What's Wrong or Missing?

Claude Code v2.1.110 fixed plugin installation so dependencies declared in plugin.json are honored even when the marketplace entry omits them, and /plugin install now lists auto-installed dependencies.

That behavior is currently undocumented:

1. The plugin.json schema does not document a dependency field for plugin-to-plugin dependencies.
2. The install docs do not explain that installing one plugin may automatically install dependency plugins.
3. The install docs do not explain that /plugin install now lists those auto-installed dependencies.

Without this, plugin authors do not know where to declare dependencies, and users/admins cannot tell from the docs that plugin installs may pull in additional plugins automatically.

Suggested Improvement

Update the plugin documentation to describe plugin dependency support in one place and cross-link it from install docs.

Suggested changes:

1. In plugins-reference, add the dependencies field to the plugin.json schema with its expected format and precedence rules when both plugin.json and marketplace metadata are involved.
2. In discover-plugins, add a short note under Install plugins explaining that /plugin install may auto-install dependency plugins declared by the selected plugin.
3. Document that current Claude Code versions list the auto-installed dependencies during installation.
4. In plugin-marketplaces, clarify how marketplace entries interact with dependency declarations coming from the plugin manifest when the marketplace entry does not repeat them.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Page	Line(s)	Context
https://code.claude.com/docs/en/plugins-reference	287-315	plugin.json schema lists supported fields but does not document plugin dependencies
https://code.claude.com/docs/en/discover-plugins	256-272	/plugin install docs explain basic install flow and scopes only
https://code.claude.com/docs/en/plugin-marketplaces	190-225	Marketplace entry docs refer back to manifest fields but do not cover dependency declarations

Total scope: 3 pages affected

Source: Changelog v2.1.110

Exact changelog entry:

Fixed plugin install not honoring dependencies declared in plugin.json when the marketplace entry omits them; /plugin install now lists auto-installed dependencies

[coygeek]

Issue #48864 Verification

Title: [DOCS] Plugin docs missing plugin.json dependency declarations and auto-install behavior
Issue Date: 2026-04-16
Verification Date: 2026-05-01
Status: RESOLVED

---

Issue Summary

This issue reports that three pieces of plugin dependency behavior were undocumented: (1) the dependencies field in plugin.json, (2) the fact that /plugin install auto-installs dependency plugins, and (3) the fact that /plugin install lists auto-installed dependencies in its output.

---

Verification Results

Claim 1: The plugin.json schema does not document a dependencies field

Status: RESOLVED

At https://code.claude.com/docs/en/plugins-reference, line 437, the dependencies field is fully documented in the schema table:

dependencies | array | Other plugins this plugin requires, optionally with semver version constraints. See Constrain plugin dependency versions | [{ "name": "secrets-vault", "version": "~2.1.0" }]

The schema example at lines 390–393 also includes a dependencies array demonstrating the field in context. A dedicated guide at plugin-dependencies.md (153 lines) covers version constraints, cross-marketplace dependencies, and error resolution.

---

Claim 2: The install docs do not explain that installing one plugin may auto-install dependency plugins

Status: RESOLVED

At https://code.claude.com/docs/en/plugin-dependencies, line 11:

"When you install a plugin that declares dependencies, Claude Code resolves and installs them automatically and lists which dependencies were added at the end of the install output."

At https://code.claude.com/docs/en/discover-plugins, line 276:

"When you install a plugin that declares dependencies, the install output lists which dependencies were auto-installed alongside it."

---

Claim 3: The install docs do not explain that /plugin install lists auto-installed dependencies

Status: RESOLVED

At https://code.claude.com/docs/en/discover-plugins, line 276 (quoted above), the behavior is explicitly documented. This is the same evidence as Claim 2 — both the auto-install and the listing behavior are covered in a single sentence.

---

Current State

Claim	Status
plugin.json schema missing dependencies field	RESOLVED
Install docs missing auto-install behavior	RESOLVED
Install docs missing listing of auto-installed deps	RESOLVED

---

Suggested Fix

N/A - issue has been resolved. All three pieces of behavior are now documented.

---

References

• URL: https://code.claude.com/docs/en/plugins-reference (lines 390–437: schema example and dependencies field entry)
• URL: https://code.claude.com/docs/en/discover-plugins (line 276: auto-install listing in install output)
• URL: https://code.claude.com/docs/en/plugin-dependencies (line 11: auto-install behavior; full 153-line guide covering version constraints and error resolution)
• URL: https://code.claude.com/docs/en/plugin-marketplaces (line 182: allowCrossMarketplaceDependenciesOn field cross-linked to plugin-dependencies guide)

---

Conclusion & Recommendation

Primary Concern: Plugin dependency declarations in plugin.json and the auto-install/listing behavior of /plugin install were undocumented.

Resolution Status: RESOLVED

Recommendation: CLOSE

Anthropic has addressed all three gaps identified in the issue. A dedicated plugin-dependencies.md guide (153 lines) now documents version constraints and cross-marketplace dependencies, the plugin.json schema explicitly includes the dependencies field with a link to that guide, and the install instructions in discover-plugins.md state that the install output lists auto-installed dependencies.

[github-actions]

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.