[DOCS] Plugin uninstall docs missing settings.local.json behavior for project-scoped plugins

[coygeek]

Documentation Type

Missing documentation (feature not documented)

Documentation Location

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

Section/Topic

/plugin uninstall section; also plugins-reference.md plugin uninstall command reference

Current Documentation

discover-plugins.md documents /plugin uninstall:

/plugin uninstall plugin-name@marketplace-name

"The --scope option lets you target a specific scope with CLI commands:"

claude plugin uninstall formatter@your-org --scope project

plugins-reference.md documents the uninstall command with its --scope option (user, project, or local) but makes no mention of which settings file is written to when uninstalling a project-scoped plugin.

settings.md shows the scopes table mapping local scope to .claude/settings.local.json but does not address uninstall behavior.

What's Wrong or Missing?

Changelog v2.1.71 documents a behavioral change:

"Improved /plugin uninstall to disable project-scoped plugins in .claude/settings.local.json instead of modifying .claude/settings.json, so changes don't affect teammates"

This reveals a deliberate asymmetry in the plugin scope system that is completely undocumented:

• Installing a project-scoped plugin writes to .claude/settings.json (shared with teammates, committed to version control)
• Uninstalling a project-scoped plugin now writes the disable/removal record to .claude/settings.local.json (gitignored, personal — not shared with teammates)

Without this documentation, users making these assumptions will be surprised:

1. A user who runs /plugin uninstall on a project-scoped plugin will expect it to be removed from settings.json (symmetrical with install). It is not.
2. A user who wants to remove a plugin for their whole team via uninstall will find the change is not committed.
3. A user who inspects settings.json after uninstalling a project-scoped plugin will find no change and assume the uninstall failed.

The correct workflow to remove a plugin for all teammates is to remove it from settings.json directly — not to use /plugin uninstall.

Suggested Improvement

Add a note to the /plugin uninstall section in discover-plugins.md:

Project-scoped plugins: Uninstalling a project-scoped plugin writes the disable record to .claude/settings.local.json (gitignored), not .claude/settings.json. This means the uninstall is local to you and does not affect teammates. To remove a plugin for the entire team, remove it from .claude/settings.json directly.

Update the plugin uninstall entry in plugins-reference.md to include the same note.

Impact

High - Prevents users from using a feature

Additional Context

Affected Pages:

Page	Context
https://code.claude.com/docs/en/discover-plugins	/plugin uninstall — no mention of settings.local.json behavior
https://code.claude.com/docs/en/plugins-reference	plugin uninstall command reference — no file location documented
https://code.claude.com/docs/en/settings	Plugin scope table — implied symmetry not corrected

Total scope: 3 pages affected

Source: Changelog v2.1.71

Exact changelog entry:

"Improved /plugin uninstall to disable project-scoped plugins in .claude/settings.local.json instead of modifying .claude/settings.json, so changes don't affect teammates"

[coygeek]

Still unresolved as of 2026-03-28 after re-checking the current docs. The documentation gap described in this issue is still present.

[coygeek]

Quickly checked the latest docs again. This issue is still unresolved, so it should stay open.

[coygeek]

Still relevant as of 2026-05-18. This documentation gap has not been addressed in the docs yet.

[coygeek]

Verified against the latest docs; this still appears unresolved.