Help us improve
Share bugs, ideas, or general feedback.
From plugin-management
This skill should be used when the user asks to "install a plugin", "update a plugin", "remove a plugin", "check if a plugin is loaded", "reload plugins", "why isn't my plugin working", "what needs a restart", "hot reload", "plugin cache", "plugin settings", "enable a plugin", "disable a plugin", "validate a plugin", or mentions plugin installation, updates, troubleshooting, or lifecycle management in Claude Code.
npx claudepluginhub nsheaps/ai-mktpl --plugin plugin-managementHow this skill is triggered — by the user, by Claude, or both
Slash command
/plugin-management:plugin-managementThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
Guide for installing, updating, verifying, and troubleshooting Claude Code plugins. Covers what
Guides Claude Code plugin creation, structure (plugin.json, commands/agents/skills/hooks), installation (/plugin), marketplaces, team workflows, testing, debugging, and settings. Delegates to docs-management.
Guides Claude Code plugin setup including directory structure, plugin.json manifest, component organization for commands/agents/skills/hooks, auto-discovery, and naming conventions.
Guides creation and organization of Claude Code plugins: directory layout, plugin.json manifest, component structure for commands, agents, skills, and hooks.
Share bugs, ideas, or general feedback.
Guide for installing, updating, verifying, and troubleshooting Claude Code plugins. Covers what hot-reloads, what requires a restart, and common failure modes.
Install from a configured marketplace:
/plugin install plugin-name@marketplace-name
Scopes control where the plugin entry is stored:
| Scope | Settings File | Persists For |
|---|---|---|
user | ~/.claude/settings.json | All projects for this user |
project | .claude/settings.json (repo root) | All users of this project |
local | .claude/settings.local.json | This user in this project only |
The plugin is downloaded and cached at ~/.claude/plugins/cache/.
Load a local plugin for the current session only:
claude --plugin-dir /path/to/my-plugin
This does not persist — the plugin is only available for that session. Use this during plugin
development to test changes. A restart is required to pick up code changes even with --plugin-dir.
Add marketplaces and plugins in settings files:
{
"extraKnownMarketplaces": ["nsheaps/ai-mktpl"],
"enabledPlugins": ["plugin-name@nsheaps/ai-mktpl"]
}
This can go in user, project, or local settings depending on desired scope.
Plugin updates are fetched when Claude Code starts or when explicitly triggered:
/plugin and use the UI to check for updatesAfter an update, the cached copy at ~/.claude/plugins/cache/ is replaced.
Known issue: After a plugin update, ${CLAUDE_PLUGIN_ROOT} in settings.json may retain the
old versioned cache path, causing hook failures. See references/known-issues.md for the workaround.
This is the most critical knowledge for plugin management. The rule is simple:
Only
settings.jsonfiles are truly file-watched. Everything else uses memoized caching that clears at lifecycle boundaries (/clear,/compact, plugin operations).
| Component | Hot-Reloads? | Notes |
|---|---|---|
settings.json changes | Immediate | Chokidar file watcher + event bus |
| Plugin install/uninstall | Immediate (v2.1.45+) | Cache invalidation on install |
| Plugin enable/disable | Immediate | Settings change triggers cache clear |
| Skills (SKILL.md content) | On /clear or /compact | Memoized, not file-watched |
| CLAUDE.md / rules files | On /clear or /compact | Same memoization pattern |
| Hook configs | On plugin reload | Cleared when plugin cache invalidated |
| MCP server configs | Restart required | Not file-watched, connections persist |
| Plugin code/manifest | Restart required | Cached at install time |
--plugin-dir code changes | Restart required | Explicitly documented |
| Agent file changes | Restart required | Not watched |
For the full breakdown with source references, see references/reload-behavior.md.
/clear to pick up changes.settings.json? Takes effect immediately./plugin
The plugin UI shows:
claude --debug
# or within a session:
/debug
Shows plugin loading diagnostics including load order and any failures.
claude plugin validate /path/to/plugin
Checks the plugin manifest (plugin.json) for structural correctness.
/help
Plugin skills appear as /plugin-name:skill-name in the help output. If a skill is missing,
the plugin may have failed to load — check /plugin errors tab.
/plugin
Use the plugin UI to uninstall. This removes the entry from the relevant settings file and clears the cached copy.
Remove the plugin entry from the appropriate settings file (enabledPlugins array) and
optionally delete the cache at ~/.claude/plugins/cache/<plugin-hash>/.
| Symptom | Likely Cause | Fix |
|---|---|---|
Plugin not appearing in /plugin | Not in enabledPlugins or marketplace not configured | Check settings files for correct entries |
| Skill not triggering | SKILL.md loaded before latest change | Run /clear to refresh memoized cache |
| Hook not firing after update | ${CLAUDE_PLUGIN_ROOT} pointing to old path | See references/known-issues.md |
| MCP server not connecting | Config not reloaded | Restart Claude Code |
| "Plugin failed to load" error | Invalid plugin.json manifest | Run claude plugin validate |
Plugin works with --plugin-dir but not installed | Cache stale or settings misconfigured | Uninstall, reinstall, restart |
references/reload-behavior.md — Detailed hot-reload matrix with source code references and
GitHub issue links for each componentreferences/known-issues.md — Known bugs, workarounds, and upstream issue tracking linksplugin-dev:plugin-structure — Creating new plugins (directory layout, manifest, components)plugin-dev:skill-development — Writing effective skills for pluginsplugin-dev:hook-development — Creating and testing plugin hooksplugin-dev:mcp-integration — Configuring MCP servers in plugins