Claude Skills Troubleshooting

Overview

Quick Diagnosis

python3 scripts/diagnose_plugins.py

• 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

• /plugin

  shows plugin as installed
• Skill not appearing in Skill tool's available list
• Plugin metadata exists in

  installed_plugins.json

installed_plugins.json

enabledPlugins

settings.json

# 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"

# 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

~/.claude/plugins/installed_plugins.json

~/.claude/settings.json

enabledPlugins

~/.claude/plugins/known_marketplaces.json

~/.claude/plugins/cache/

1. Exists in

   installed_plugins.json

   (registered)
2. Listed in

   settings.json

   →

   enabledPlugins

   with value

   true

Issue 3: Marketplace Cache Stale

• GitHub has latest changes
• Install finds plugin but gets old version
• Newly added plugins not visible

# 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

1. Local changes not pushed to GitHub - Most common!
   bash

   git status
   git push
   claude plugin marketplace update marketplace-name

2. marketplace.json configuration error
   bash

   python3 -m json.tool .claude-plugin/marketplace.json

3. Skill directory missing
   bash

   ls -la skill-name/SKILL.md

Diagnostic Commands Reference

claude plugin marketplace list

claude plugin marketplace update {name}

claude plugin install {plugin}@{marketplace}

claude plugin enable {plugin}@{marketplace}

claude plugin disable {plugin}@{marketplace}

claude plugin uninstall {plugin}@{marketplace}

cat ~/.claude/plugins/installed_plugins.json | jq '.plugins | keys'

cat ~/.claude/settings.json | jq '.enabledPlugins'

Batch Enable Missing Plugins

python3 scripts/enable_all_plugins.py marketplace-name

Skills vs Commands Architecture

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

     )

References

• See

  references/known_issues.md

  for GitHub issue tracking
• See

  references/architecture.md

  for detailed plugin architecture