Diagnose and resolve Claude Code plugin and skill issues. This skill should be used when plugins are installed but not showing in available skills list, skills are not activating as expected, or when troubleshooting enabledPlugins configuration in settings.json. Triggers include "plugin not working"

Claude Skills Troubleshooting Overview Diagnose and resolve common Claude Code plugin and skill configuration issues. This skill provides systematic debugging workflows for plugin installation, enablement, and activation problems. Quick Diagnosis Run the diagnostic script to identify common issues: The script checks: Installed vs enabled plugins mismatch in both directions (installed but not enabled and enabled but not registered) Missing enabledPlugins entries in settings.json Stale marketplace cache using known marketplaces.json lastUpdated Missing, malformed, timezone free, or future lastUpdated metadata Invalid plugin configurations Treat lastUpdated as the only cache freshness source. Do not fall back to cache directory modification times: marketplace updates can refresh nested files without changing that directory timestamp. The diagnostic exits nonzero for stale caches or invalid freshness metadata. Common Issues Issue 1: Plugin Installed But Not Showing in Available Skills Symptoms: /plugin shows plugin as installed Skill not appearing in Skill tool's available list Plugin metadata exists in installed plugins.json Root Cause: Known bug ([GitHub 17832](https://github.com/anthropics/claude code/issues/17832)) plugins are added to installed plugins.json but NOT automatically added to enabledPlugins in settings.json . Diagnosis: Solution: Mirror variant — enabled but not registered: If diagnosis instead shows the plugin in enabledPlugins but NOT in installed plugins.json , the cause is the symlink skip bug: the install ran under a config dir where installed plugins.json is a symlink (multi profile shared setups), and the CLI silently skipped writing it. See references/known issues.md → "Symlinked installed plugins.json". Fix: Issue 2: Understanding Plugin State Architecture Key files: File Purpose ~/.claude/plugins/installed plugins.json Registry of ALL plugins (installed + disabled) ~/.claude/settings.json → enabledPlugins Controls which plugins are ACTIVE ~/.claude/plugins/known marketplaces.json Registered marketplace sources ~/.claude/plugins/cache/ Actual plugin files A plugin is active ONLY when: 1. Exists in installed plugins.json (registered) 2. Listed in settings.json → enabledPlugins with value true Issue 3: Marketplace Cache Stale Symptoms: GitHub has latest changes Install finds plugin but gets old version Newly added plugins not visible Solution: Issue 4: Plugin Not Found in Marketplace Common causes (in order of likelihood): 1. Local changes not pushed to GitHub Most common! 2. marketplace.json configuration error 3. Skill directory missing Diagnostic Commands Reference Purpose Command List marketplaces claude plugin marketplace list Update marketplace claude plugin marketplace update {name} Install plugin claude plugin install {plugin}@{marketplace} Enable plugin claude plugin enable {plugin}@{marketplace} Disable plugin claude plugin disable {plugin}@{marketplace} Uninstall plugin claude plugin uninstall {plugin}@{marketplace} Check installed cat ~/.claude/plugins/installed plugins.json \ jq '.plugins \ keys' Check enabled cat ~/.claude/settings.json \ jq '.enabledPlugins' Batch Enable Missing Plugins To enable all installed but disabled plugins from a marketplace: Skills vs Commands Architecture Claude Code has two types of user invocable extensions: 1. Skills (in skills/ directory) Auto activated based on description matching Loaded when user request matches skill description 2. Commands (in commands/ directory) Explicitly invocable via /command name Appears in Skill tool's available list Requires command file (e.g., commands/seer.md ) If a skill should be explicitly invocable, add a corresponding command file. References See references/known issues.md for GitHub issue tracking See references/architecture.md for detailed plugin architecture

claude-skills-troubleshooting