claude-code - 💡(How to fix) Fix [DOCS] Plugin docs missing dependency declaration and marketplace auto-resolution behavior [1 participants]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

plugin.json manifest/schema docs and the plugin marketplace install flow for plugin dependencies

Current Documentation

The plugin installation guide currently describes marketplaces as a simple two-step flow:

A marketplace is a catalog of plugins that someone else has created and shared. Using a marketplace is a two-step process:

Add the marketplace This registers the catalog with Claude Code so you can browse what's available. No plugins are installed yet.

Install individual plugins Browse the catalog and install the plugins you want.

The plugin manifest reference currently shows this plugin.json schema:

{ "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 marketplace schema likewise says plugin entries can include manifest fields plus marketplace-specific fields, but only documents:

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.

The CLI docs for adding marketplaces currently say only:

claude plugin marketplace add <source> [options]

<source>: GitHub owner/repo shorthand, git URL, remote URL to a marketplace.json file, or local directory path.

What's Wrong or Missing?

Changelog v2.1.117 describes plugin dependency behavior that is not documented in the plugin docs:

Plugin dependency errors now say "not installed" with an install hint, and claude plugin marketplace add now auto-resolves missing dependencies from configured marketplaces.

The current docs do not explain plugin-to-plugin dependencies at all.

A. No documented way to declare plugin dependencies

The plugin.json reference does not document any dependency field or dependency semantics, so plugin authors cannot learn how to declare that one plugin requires another.

B. No documented user-facing dependency resolution behavior

The install and marketplace guides do not explain what happens when a required plugin dependency is missing, what the new "not installed" error means, or when Claude Code offers an install hint.

C. Marketplace add side effects are undocumented

discover-plugins currently says adding a marketplace only registers the catalog and installs nothing yet, but the v2.1.117 behavior implies claude plugin marketplace add can now resolve missing plugin dependencies from already-configured marketplaces. That dependency-resolution behavior is not described anywhere.

Suggested Improvement

Document plugin dependencies as a first-class part of the plugin system.

Suggested updates:

1. In plugins-reference, add the dependency field(s) supported in plugin.json, including format, scope, and resolution rules.
2. In discover-plugins, add a short section explaining missing-dependency errors, the new install hint wording, and whether dependency plugins are auto-installed or prompted.
3. In plugin-marketplaces, document that claude plugin marketplace add can resolve missing dependencies from configured marketplaces, including what counts as a configured marketplace.
4. Clarify the "No plugins are installed yet" wording so it matches current dependency auto-resolution behavior, or explicitly call out dependency-related exceptions.
5. Add one end-to-end example showing a plugin that depends on another plugin and how Claude Code resolves it.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 pages affected

Source: Changelog v2.1.117

Exact changelog entry: Plugin dependency errors now say "not installed" with an install hint, and claude plugin marketplace add now auto-resolves missing dependencies from configured marketplaces