claude-code - 💡(How to fix) Fix [DOCS] Plugin docs missing `plugin.json` dependency declarations and auto-install behavior [1 participants]

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": "[email protected]",
    "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:

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