claude-code - 💡(How to fix) Fix [DOCS] Plugin docs missing dependency auto-install behavior for `/reload-plugins` and marketplace auto-update

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

plugin.json manifest schema and plugin dependency installation behavior for /reload-plugins and marketplace auto-update

Current Documentation

The docs currently say:

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 plugin discovery docs also say:

When you install, enable, or disable plugins during a session, run /reload-plugins to pick up all changes without restarting:

/reload-plugins

Claude Code reloads all active plugins and shows counts for plugins, skills, agents, hooks, plugin MCP servers, and plugin LSP servers.

And the marketplace docs say:

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. If any plugins were updated, you'll see a notification prompting you to run /reload-plugins.

What's Wrong or Missing?

A. Plugin dependency declarations are undocumented

The plugin manifest reference says it documents all supported plugin.json fields, but it does not describe any field or syntax for declaring plugin dependencies.

B. Dependency auto-install behavior is undocumented

The docs for /reload-plugins and marketplace auto-update explain reload/update at a high level, but they do not say these flows can now auto-install missing plugin dependencies from marketplaces the user has already added.

C. The prerequisite is missing

The changelog entry for v2.1.116 makes the scope explicit: dependency auto-install only works for dependencies resolvable from marketplaces that are already configured. The current docs do not explain that prerequisite or what users should expect when a required marketplace has not been added yet.

Suggested Improvement

Add a dedicated Plugin dependencies subsection to plugins-reference that documents:

1. Which plugin.json field(s) declare plugin dependencies
2. The expected schema for those declarations
3. How Claude Code resolves dependencies across configured marketplaces
4. What happens during /plugin install, /reload-plugins, and background marketplace auto-update when a dependency is missing
5. What happens when the dependency's marketplace has not been added yet

Then update the user-facing workflow docs to mention the new behavior:

• discover-plugins: note that /reload-plugins can auto-install missing dependency plugins
• plugin-marketplaces: note that startup auto-update can auto-install missing dependency plugins from already-added marketplaces
• commands: expand the /reload-plugins entry so users know it may install required dependency plugins in addition to reloading active plugins

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 pages affected

Source: Changelog v2.1.116

Exact changelog entry:

/reload-plugins and background plugin auto-update now auto-install missing plugin dependencies from marketplaces you've already added`