Claude Skills Troubleshooting

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:

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:

# 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):

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

   git status
   git push
   claude plugin marketplace update marketplace-name

2. marketplace.json configuration error

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

3. Skill directory missing

   ls -la skill-name/SKILL.md

Diagnostic Commands Reference

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:

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 Code Plugin Architecture

Directory Structure

~/.claude/
├── settings.json                    # User settings including enabledPlugins
├── plugins/
│   ├── installed_plugins.json       # Registry of ALL plugins (enabled + disabled)
│   ├── known_marketplaces.json      # Registered marketplace sources
│   ├── marketplaces/                # Marketplace git clones
│   │   ├── marketplace-name/
│   │   │   └── .claude-plugin/
│   │   │       └── marketplace.json # Plugin definitions
│   │   └── ...
│   └── cache/                       # Installed plugin files
│       └── marketplace-name/
│           └── plugin-name/
│               └── version/
│                   └── skill-name/
│                       ├── SKILL.md
│                       ├── scripts/
│                       └── references/
└── skills/                          # Personal skills (not from marketplace)

Plugin Lifecycle

Installation Flow

1. User runs: claude plugin install plugin@marketplace
       ↓
2. CLI reads marketplace.json from marketplace directory
       ↓
3. Plugin files copied to cache:
   ~/.claude/plugins/cache/marketplace/plugin/version/
       ↓
4. Entry added to installed_plugins.json:
   { "plugin@marketplace": [{ "version": "1.0.0", ... }] }
       ↓
5. ⚠️ BUG: Entry NOT automatically added to settings.json enabledPlugins
       ↓
6. User must manually enable:
   claude plugin enable plugin@marketplace
       ↓
7. Entry added to settings.json:
   { "enabledPlugins": { "plugin@marketplace": true } }

Activation Flow

1. Claude Code starts
       ↓
2. Reads settings.json → enabledPlugins
       ↓
3. For each enabled plugin:
   - Loads skill metadata (name + description)
   - Metadata added to system prompt
       ↓
4. User sends message
       ↓
5. Claude matches message against skill descriptions
       ↓
6. Matching skill's SKILL.md loaded into context
       ↓
7. Claude uses skill instructions to respond

Key Files Explained

installed_plugins.json

Purpose: Registry of all plugins ever installed (NOT just active ones).

Structure:

{
  "version": 2,
  "plugins": {
    "plugin-name@marketplace": [
      {
        "scope": "user",
        "installPath": "~/.claude/plugins/cache/...",
        "version": "1.0.0",
        "installedAt": "2025-01-01T00:00:00.000Z"
      }
    ]
  }
}

Note: A plugin listed here is NOT necessarily active. Check settings.json for actual enabled state.

settings.json

Purpose: User preferences and enabled plugins.

Relevant section:

{
  "enabledPlugins": {
    "plugin-name@marketplace": true,
    "another-plugin@marketplace": true
  }
}

Important: Only plugins with true value are loaded at startup.

known_marketplaces.json

Purpose: Registry of marketplace sources.

Structure:

{
  "marketplace-name": {
    "source": {
      "source": "github",
      "repo": "owner/repo"
    },
    "installLocation": "~/.claude/plugins/marketplaces/marketplace-name",
    "lastUpdated": "2025-01-01T00:00:00.000Z"
  }
}

marketplace.json (in marketplace repo)

Purpose: Defines available plugins in a marketplace.

Location: .claude-plugin/marketplace.json

Structure:

{
  "name": "marketplace-name",
  "metadata": {
    "version": "1.0.0",
    "description": "..."
  },
  "plugins": [
    {
      "name": "plugin-name",
      "description": "...",
      "source": "./skill-directory",
      "version": "1.0.0"
    }
  ]
}

Plugin vs Skill vs Command

Plugin

• Distribution unit that packages one or more skills
• Defined in marketplace.json
• Installed via claude plugin install

Skill

• Functional unit with SKILL.md and optional resources
• Auto-activates based on description matching
• Located in skills/ directory

Command

• Explicit slash command (e.g., /seer)
• Defined in commands/ directory
• Appears in Skill tool's available list
• Must be explicitly invoked by user

Scopes

Plugins can be installed in different scopes:

Common Misconceptions

1. installed_plugins.json = active plugins

• Reality: It's a registry of ALL plugins, including disabled ones

2. Plugins auto-enable after install

• Reality: Bug prevents auto-enable; manual step required

3. Updating local files updates the plugin

• Reality: Must push to GitHub, then update marketplace cache

4. Cache is just for performance

• Reality: Cache IS where plugins live; deleting it uninstalls plugins

Known Claude Code Plugin Issues

This document tracks known bugs and issues related to Claude Code plugins.

Open Issues

GitHub #17832 - Plugins Not Auto-Enabled After Install

Status: OPEN URL: https://github.com/anthropics/claude-code/issues/17832

Problem: When installing a plugin from a marketplace, Claude Code adds the plugin to installed_plugins.json but does NOT add it to settings.json enabledPlugins.

Impact: Plugins appear "installed" but don't function. Skills silently fail to load.

Workaround: Manually enable via CLI or edit settings.json:

claude plugin enable plugin-name@marketplace

---

GitHub #19696 - installed_plugins.json Naming Misleading

Status: OPEN URL: https://github.com/anthropics/claude-code/issues/19696

Problem: The file installed_plugins.json contains ALL plugins ever registered, including disabled ones. The actual enabled state is tracked separately in settings.json.

Impact: Confusing for developers - file shows many plugins but only some are active.

Note: This is a naming/documentation issue, not a functional bug.

---

GitHub #17089 - Local Plugins Breaking After 2.1.x Update

Status: Reported URL: https://github.com/anthropics/claude-code/issues/17089

Problem: Local plugins no longer persist after the 2.1.x update.

Workaround: Create a marketplace wrapper structure for local plugins.

---

GitHub #13543 - MCP Servers from Marketplace Not Available

Status: Reported URL: https://github.com/anthropics/claude-code/issues/13543

Problem: After updating to Claude Code 2.0.64, MCP servers defined in marketplace plugins were no longer available.

---

GitHub #16260 - Contradictory Scope Error Messages

Status: Reported URL: https://github.com/anthropics/claude-code/issues/16260

Problem: CLI gives contradictory error messages about plugin scope.

Workaround: Manually edit settings.json to fix scope issues.

Resolved Issues

(Add resolved issues here as they are fixed)

Related Documentation

• Plugins Reference
• Claude Code Settings