nsheaps/plugin-management
plugins/plugin-management/skills/plugin-management/SKILL.md
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.
$ install --global
skillsauthnpx skillsauth add nsheaps/ai-mktpl plugin-managementInstall this skill globally with one command. Works with Claude Code, Cursor, and Windsurf.
Security Scan Results
3 of 9 scanners reported clean
Some scanners were skipped, did not run, or reported a non-clean status. Review each row below.
3
Scanners Passed
9
Scanners in report
Clean
TrivyContainer and dependency vulnerability scanner
95%
Clean
SemgrepStatic code analysis for vulnerabilities
95%
Clean
mcp-scan (Snyk)Model Context Protocol security validation
95%
Skipped
Snyk (dep)Open source security scanning
50%
Skipped
Socket.devSupply chain security analysis
50%
Skipped
VirusTotalMulti-engine malware detection
50%
Skipped
CrowdStrikeAdvanced threat intelligence
50%
Skipped
OSV-ScannerOpen Source Vulnerability database check
50%
Skipped
OWASP Dep-Check
50%
Last scanned: Apr 22, 2026, 4:12 PM45.8s3 files scanned
SKILL.md
- name:
- plugin-management
- description:
- >
Plugin Installation and Management
Guide for installing, updating, verifying, and troubleshooting Claude Code plugins. Covers what hot-reloads, what requires a restart, and common failure modes.
Installation Methods
Method 1: Marketplace (Recommended)
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/.
Method 2: Plugin Directory (Development/Testing)
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.
Method 3: Team Configuration
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.
Updating Plugins
Plugin updates are fetched when Claude Code starts or when explicitly triggered:
- Automatic: Claude Code checks for updates on session start
- Manual: Run
/pluginand use the UI to check for updates - Force reinstall: Uninstall and reinstall to get the latest version
After 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.
What Requires a Restart vs What Hot-Reloads
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).
Quick Reference
| 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.
Practical Implications
- Editing a SKILL.md? Run
/clearto pick up changes. - Changed a hook script? The script itself runs fresh each time (it's a file on disk), but hook configuration (which hooks fire on which events) requires a plugin reload or restart.
- Added an MCP server? Must restart Claude Code.
- Changed
settings.json? Takes effect immediately.
Verifying Plugin Status
Check Installed Plugins
/plugin
The plugin UI shows:
- Installed tab: All loaded plugins with version and source
- Errors tab: Plugins that failed to load (manifest issues, missing files)
Debug Mode
claude --debug
# or within a session:
/debug
Shows plugin loading diagnostics including load order and any failures.
Validate Plugin Structure
claude plugin validate /path/to/plugin
Checks the plugin manifest (plugin.json) for structural correctness.
Verify Skills Loaded
/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.
Removing Plugins
Uninstall
/plugin
Use the plugin UI to uninstall. This removes the entry from the relevant settings file and clears the cached copy.
Manual Removal
Remove the plugin entry from the appropriate settings file (enabledPlugins array) and
optionally delete the cache at ~/.claude/plugins/cache/<plugin-hash>/.
Troubleshooting
| 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 |
Additional Resources
Reference Files
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 links
Related Skills
plugin-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
Related Skills
nsheaps/github-app-session-env
tools
VerifiedTrustedCommunity
Manually reproduce what the github-app plugin's SessionStart hook does to make a GitHub App installation token usable in the current session — materialize the PEM, generate the token, isolate GH_CONFIG_DIR, write the runtime env file, and wire CLAUDE_ENV_FILE so every Bash call sees GH_TOKEN/GITHUB_TOKEN. Use when the hook did not run, the token is missing from the environment, or a shell/teammate needs the token wired up by hand. <example>GH_TOKEN isn't set even though github-app is configured</example> <example>the github-app SessionStart hook didn't run, set up the token manually</example> <example>wire the github app token into CLAUDE_ENV_FILE</example> <example>gh keeps falling back to the wrong account, isolate GH_CONFIG_DIR</example>
3SKILL.mdUpdated Jun 9, 2026
nsheaps/github-app-git-identity
tools
VerifiedTrustedCommunity
Manually configure the GitHub App bot git identity the way the github-app plugin's SessionStart hook does — resolve the app slug and bot user ID, build the <slug>[bot] name and noreply email, set GIT_AUTHOR_*/GIT_COMMITTER_* env vars, and write an isolated GIT_CONFIG_GLOBAL with the gh auth git-credential helper. Use when commits are attributed to the wrong account, "Author identity unknown" appears, or git identity must be set up by hand. <example>my commits are showing up as the handler, not the bot</example> <example>git says Author identity unknown after the github-app hook ran</example> <example>configure the github app bot git identity manually</example> <example>set up the gh credential helper for git push</example>
3SKILL.mdUpdated Jun 9, 2026
nsheaps/spec-management
tools
VerifiedTrustedCommunity
Manages spec files for requirements capture and validation
3SKILL.mdUpdated Jun 7, 2026
nsheaps/plugins/bash-command-rejection/skills/bash-chaining-alternatives
tools
VerifiedTrustedCommunity
# Bash Chaining Alternatives This skill teaches you how to work around the bash command chaining restriction enforced by this plugin. ## Why Chaining is Blocked The `bash-command-rejection` plugin blocks these operators: | Operator | Name | Why Blocked | | -------- | ---------- | ----------------------------------------------------------------------------------- | | `&&` | AND chain | Runs cmd2 only if cmd1 su
3SKILL.mdUpdated Jun 7, 2026