[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 totrue. Set tofalsefor plugins that should install in a disabled state until the user enables them with/pluginorclaude 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 setsdefaultEnabled: false. Enable them from the/pluginInstalled tab or withclaude plugin enable <plugin>.
Impact
Medium - Makes feature difficult to understand
Additional Context
Affected Pages:
| Page | Context |
|------|---------|
| https://code.claude.com/docs/en/plugins-reference | Primary manifest schema and CLI enable command reference |
| https://code.claude.com/docs/en/plugin-marketplaces | Marketplace plugin entry and team marketplace documentation |
| https://code.claude.com/docs/en/discover-plugins | User-facing install and enable workflow |
| https://code.claude.com/docs/en/plugin-dependencies | Related dependency enablement behavior already documented |
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."
3 Comments
Found 3 possible duplicate issues:
This issue will be automatically closed as a duplicate in 3 days.
🤖 Generated with Claude Code
Issue #63301 Verification
Title: [DOCS] Plugin docs omit
defaultEnabled: falsefor opt-in pluginsIssue Date: 2026-05-28
Verification Date: 2026-06-23
Status: RESOLVED
---
Issue Summary
This issue reports that Claude Code v2.1.154 introduced a
defaultEnabledfield that can be set tofalsein either.claude-plugin/plugin.jsonor a marketplace entry, so a plugin installs in a disabled state until the user opts in. At the time of filing, the plugins reference schema, the marketplace guide, and the install/manage guide did not document this field, leaving plugin authors, marketplace maintainers, and users unable to discover or use the new opt-in behavior.---
Verification Results
Claim A: Plugin manifest schema does not document
defaultEnabledStatus: RESOLVED
Evidence:
>
defaultEnabled| boolean | {/ min-version: 2.1.154 /}Whether the plugin starts in an enabled state when the user has not set one. Defaults totrue. See [Default enablement](#default-enablement). Requires Claude Code v2.1.154 or later.> Set
defaultEnabled: falseinplugin.jsonto ship a plugin that installs disabled. The user turns it on withclaude plugin enable <plugin>or the/plugininterface. Use this for plugins that add cost or scope a user should opt into, such as one that connects to an external service. This requires Claude Code v2.1.154 or later. Earlier versions ignore the field and enable the plugin on install.enabledPluginssetting wins, and a dependency that is required by an active plugin gets an explicittruewritten for it.Verdict: The manifest schema and the surrounding explanation have been added as the issue requested. Plugin authors can now discover the field, its type, default value, and the precedence rules that govern it.
---
Claim B: Marketplace entry-level
defaultEnabledis undocumentedStatus: RESOLVED
Evidence:
>
defaultEnabled| boolean | {/ min-version: 2.1.154 /}Whether the plugin is enabled after install (default: true). Set tofalseto install the plugin disabled until the user opts in. Takes precedence over the same field in the plugin'splugin.json. See Default enablement. Requires Claude Code v2.1.154 or later.plugins-reference.md(line 506) explicitly states that the marketplace entry takes precedence over the same field inplugin.json.Verdict: Marketplace maintainers can now see the field, its default, the precedence order, and a cross-reference back to the canonical reference.
---
Claim C: Install/manage guide does not explain the opt-in workflow
Status: RESOLVED
Evidence:
> Run
/pluginand go to the Installed tab to view, enable, disable, or uninstall your plugins. The list is grouped by scope and sorted so you see problems first: plugins with load errors or unresolved dependencies appear at the top, followed by your favorites, with disabled plugins folded behind a collapsed header at the bottom.> Re-enable a disabled plugin:
> ``
shell``> /plugin enable plugin-name@marketplace-name
>
plugins-reference.md(line 499) tells users how to opt in:> The user turns it on with
claude plugin enable <plugin>or the/plugininterface.> This holds even when a dependency sets
defaultEnabled: falsein its manifest, because Claude Code writes an explicittruefor it. The same applies at install: a dependency pulled in to satisfy an active plugin installs withtrueregardless of its own default.Verdict: The enable workflow is now documented in the user-facing install/manage guide, and the canonical "Default enablement" subsection spells out the exact user actions (
/pluginorclaude plugin enable <plugin>) to opt in. The dependencies page is also cross-referenced, so dependency interactions are covered.---
Current State
| Claim | Status |
|-------|--------|
| A:
defaultEnableddocumented in plugin manifest schema | RESOLVED || B:
defaultEnableddocumented in marketplace entry schema | RESOLVED || C: Install/manage guide explains the opt-in enable workflow | RESOLVED |
---
Suggested Fix
N/A - issue has been resolved.
The original suggested improvements (a
defaultEnabledrow in the manifest schema, a marketplace example with the field, and a brief install/manage note) are all present in the current docs, plus a precedence-rules section and a cross-reference from the dependencies page.---
References
defaultEnabledrow in the metadata fields table.enabledPluginsand dependency requirements, and the cross-reference to the marketplace entry.defaultEnabledrow in the "Optional plugin fields" table, noting it takes precedence over the same field inplugin.json./pluginInstalled tab workflow and the/plugin enable//plugin disablecommands.defaultEnabled: falseis still enabled when pulled in by an active plugin.enabledPluginsdocumentation that points todefaultEnabledas the fallback when no entry is set at any scope.---
Conclusion & Recommendation
Primary Concern: The
defaultEnabled: falseopt-in feature shipped in v2.1.154 was not documented in the plugin manifest schema, marketplace entry schema, or the user-facing install/manage guide.Resolution Status: RESOLVED
Recommendation: CLOSE
The field is now documented in both the manifest schema and the marketplace entry schema, with a dedicated "Default enablement" subsection that explains the type, default value, precedence rules, and the user-facing
/pluginandclaude plugin enable <plugin>workflow. The dependencies page and the settings page both cross-reference the new field, so plugin authors, marketplace maintainers, and end users can all discover the behavior from the canonical pages.This issue has been automatically locked since it was closed and has not had any activity for 7 days. If you're experiencing a similar issue, please file a new issue and reference this one if it's relevant.