🇺🇸English
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:
python3 scripts/diagnose_plugins.py
The script checks:
- Installed vs enabled plugins mismatch
- Missing enabledPlugins entries in settings.json
- Stale marketplace cache
- Invalid plugin configurations
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) - plugins are added to installed_plugins.json but NOT automatically added to enabledPlugins in settings.json.
Diagnosis:
# Check if plugin is in installed_plugins.json
cat ~/.claude/plugins/installed_plugins.json | grep "plugin-name"
# Check if plugin is enabled in settings.json
cat ~/.claude/settings.json | grep "plugin-name"
Solution:
# Option 1: Use CLI to enable
claude plugin enable plugin-name@marketplace-name
# Option 2: Manually edit settings.json
# Add to enabledPlugins section:
# "plugin-name@marketplace-name": true
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:
- Exists in
installed_plugins.json (registered)
- 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:
# Update marketplace cache
claude plugin marketplace update marketplace-name
# Or clear and re-fetch
rm -rf ~/.claude/plugins/cache/marketplace-name
claude plugin marketplace update marketplace-name
Issue 4: Plugin Not Found in Marketplace
Common causes (in order of likelihood):
-
Local changes not pushed to GitHub - Most common!
git status
git push
claude plugin marketplace update marketplace-name
-
marketplace.json configuration error
python3 -m json.tool .claude-plugin/marketplace.json
-
Skill directory missing
ls -la skill-name/SKILL.md
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} |
Batch Enable Missing Plugins
To enable all installed but disabled plugins from a marketplace:
python3 scripts/enable_all_plugins.py marketplace-name
Skills vs Commands Architecture
Claude Code has two types of user-invocable extensions:
-
Skills (in skills/ directory)
- Auto-activated based on description matching
- Loaded when user request matches skill description
-
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
Weekly Installs
81
Repository
daymade/claude-…e-skills
GitHub Stars
636
First Seen
Jan 22, 2026
Security Audits
Gen Agent Trust HubWarnSocketPassSnykWarn
Installed on
claude-code65
opencode58
codex56
gemini-cli55
cursor49
github-copilot47
