docs: Install plugins at user scope, not project - #25
Merged
Conversation
A project-scoped install binds the plugin to the directory it was installed from. That record then suppresses the auto-install in every other repo: the plugin stays enabled in settings and listed by `claude plugin list`, but its skills never load, with no signal to the user. This bit datum-cloud/infra, where CLAUDE.md requires the pr-conventions and release skills. Sessions followed those instructions, found no skill, and carried on against a reconstructed guess at the conventions. Key changes: - Document user scope as the correct install scope, and note that the interactive /plugin flow asks while the CLI already defaults to it - Add recovery steps for anyone already broken, including the warning that `uninstall --scope project` strips the plugin from the repo's tracked settings.json
Contributor
Author
|
very confusing behaviour here |
2 tasks
privateip
approved these changes
Jul 30, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
A project-scoped install binds the plugin to the directory it was installed from, and that record then suppresses the auto-install in every other repo. The plugin stays enabled in settings and listed by
claude plugin list, but its skills never load — with no signal to the user.This bit
datum-cloud/infra, whoseCLAUDE.mdrequires thepr-conventionsandreleaseskills. Sessions followed those instructions, found no skill, and carried on against a reconstructed guess at the conventions. The people affected are the ones who installed the plugin earliest; anyone who never installed by hand is fine, because the repo config auto-installs correctly on a clean machine.The README's install section didn't mention scope at all, so nothing steered people away from it. This documents user scope as correct and adds recovery steps.
Test plan
enabledPluginsauto-installs the plugin on first session, no prior install record--scope userinstall restores skill loading with a stale project-scoped entry still presentclaude -pthatdatum-platformanddatum-gtmskills resolve in a repo they previously did notuninstall --scope projectstrips the plugin from the repo's tracked.claude/settings.jsonFixes #24