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-managementThis skill uses the workspace's default tool permissions.
Guide for installing, updating, verifying, and troubleshooting Claude Code plugins. Covers what
Guides Next.js Cache Components and Partial Prerendering (PPR) with cacheComponents enabled. Implements 'use cache', cacheLife(), cacheTag(), revalidateTag(), static/dynamic optimization, and cache debugging.
Migrates code, prompts, and API calls from Claude Sonnet 4.0/4.5 or Opus 4.1 to Opus 4.5, updating model strings on Anthropic, AWS, GCP, Azure platforms.
Compresses source documents into lossless, LLM-optimized distillates preserving all facts and relationships. Use for 'distill documents' or 'create distillate' requests.
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