claude-code - 💡(How to fix) Fix [DOCS] Plugin manifest docs still show top-level `themes` and `monitors` instead of `experimental` [1 participants]

Documentation Type

Incorrect/outdated documentation

Documentation Location

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

Section/Topic

Plugin manifest schema (plugin.json), especially the complete schema example, component path fields table, and inline monitor configuration guidance

Current Documentation

The docs currently say:

{
  "name": "plugin-name",
  ...
  "outputStyles": "./styles/",
  "themes": "./themes/",
  "lspServers": "./.lsp.json",
  "monitors": "./monitors.json",
  "dependencies": [

And the same page documents these as top-level manifest fields:

| themes | string|array | Color theme files/directories (replaces default themes/). See Themes | "./themes/" | | monitors | string|array | Background Monitor configurations that start automatically when the plugin is active. See Monitors | "./monitors.json" |

It also says:

Location: monitors/monitors.json in the plugin root, or inline in plugin.json

To declare monitors inline, set the monitors key in plugin.json to the same array. To load from a non-default path, set monitors to a relative path string such as "./config/monitors.json".

What's Wrong or Missing?

This page still teaches plugin authors to declare themes and monitors at the top level of plugin.json.

For the v2.1.129 change, these declarations should now live under an experimental object instead. Top-level declarations still work for compatibility, but claude plugin validate warns about them.

Because the reference page only shows the older top-level shape and does not mention experimental or the validator warning, plugin authors following the docs will get warnings from claude plugin validate even when they copied the documented schema.

Suggested Improvement

Update plugins-reference so the manifest schema matches the current validator behavior:

1. Change the complete plugin.json example to move themes and monitors under "experimental": { ... }.
2. Update the component field documentation to explain that themes and monitors are now declared inside experimental.
3. Update the inline monitors guidance so it points to experimental.monitors instead of a top-level monitors key.
4. Add a short migration note that top-level themes and monitors are still accepted for backward compatibility, but claude plugin validate warns and new manifests should use experimental.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 1 page affected

Changelog context: This issue cross-references the Claude Code v2.1.129 release entry that says plugin manifests should now declare themes and monitors under experimental, while top-level declarations remain backward-compatible but produce claude plugin validate warnings.