claude-code - 💡(How to fix) Fix [DOCS] Plugin docs omit `defaultEnabled: false` for opt-in plugins

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

Plugin manifest schema and marketplace plugin entry fields

Current Documentation

The plugins reference introduces the manifest schema as exhaustive:

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

The complete schema example includes metadata, component path fields, user-facing configuration, channels, and dependencies, but no defaultEnabled field:

"dependencies": [ "helper-lib", { "name": "secrets-vault", "version": "~2.1.0" } ]

The plugin marketplaces guide documents how teams can force specific plugins on through settings:

You can also specify which plugins should be enabled by default:

"enabledPlugins": { "code-formatter@company-tools": true, "deployment-tools@company-tools": true }

No current plugin docs page documents a defaultEnabled field in plugin.json or in a marketplace plugin entry.

What's Wrong or Missing?

Claude Code v2.1.154 adds a way for plugin authors or marketplace maintainers to declare an installed plugin as opt-in by setting defaultEnabled: false in either .claude-plugin/plugin.json or the marketplace entry.

The docs currently explain how users and teams can enable plugins after installation, and how settings can pre-enable specific plugins, but they do not document this author-controlled default-enabled behavior.

That leaves three gaps:

A. Plugin authors cannot discover the manifest field

The manifest schema says it documents all supported fields, but it does not list defaultEnabled, its type, default value, or how it interacts with component loading.

B. Marketplace maintainers cannot discover the entry-level field

The marketplace guide documents plugin source fields and team-level enabledPlugins settings, but not that a marketplace entry can set defaultEnabled: false for plugins that should install without immediately becoming active.

C. Users cannot tell how to activate opt-in plugins

The release note says opt-in plugins can be enabled with /plugin or claude plugin enable, but the install and marketplace docs do not explain that workflow for plugins that install disabled by default.

Suggested Improvement

Add defaultEnabled to the plugin manifest schema and marketplace plugin entry documentation.

Suggested minimum addition for the plugins reference:

defaultEnabled | boolean | Whether the plugin should be enabled immediately after install. Defaults to true. Set to false for plugins that should install in a disabled state until the user enables them with /plugin or claude plugin enable. Dependencies of enabled plugins are still enabled automatically.

Add a short marketplace example showing both declaration locations:

{
"name": "heavy-analysis-plugin",
"source": "./plugins/heavy-analysis-plugin",
"defaultEnabled": false
}

Also add a short note in the install/manage plugins guide:

Some plugins may install disabled by default when their author or marketplace sets defaultEnabled: false. Enable them from the /plugin Installed tab or with claude plugin enable <plugin>.

Impact

Medium - Makes feature difficult to understand

Additional Context

Affected Pages:

Total scope: 4 pages affected

Version context: Claude Code v2.1.154 changelog entry: "Plugins can now declare defaultEnabled: false in plugin.json or a marketplace entry; enable them with /plugin or claude plugin enable. Dependencies of enabled plugins are still enabled automatically."