Skip to main content
skill CX Codex

claude-skills-troubleshooting — Claude Code skill

claude-skills-troubleshooting finds why a Claude Code plugin or skill fails to appear or activate. Useful for checking plugin records, settings, and marketplace cache state.

MIT 990 installs ★ 1,540 updated 2026-10-25

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a claude-code
Open on GitHub

What claude-skills-troubleshooting does

This skill investigates Claude Code cases where an installed plugin is missing from the available skills, fails to activate, or is absent from enabledPlugins in settings.json. It compares installed_plugins.json with the active settings, checks registered marketplaces, and examines cache freshness metadata.

The package includes scripts/diagnose_plugins.py for automated checks and scripts/enable_all_plugins.py for enabling installed plugins from a marketplace. Its workflows also cover marketplace updates, marketplace.json validation, missing SKILL.md files, and the symlink case for installed_plugins.json. A plugin is active only when it is registered in installed_plugins.json and has true under enabledPlugins, so installation alone may leave it inactive.

The skill can be installed for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode. Running the diagnostic scripts requires access to the Claude Code configuration files and Python 3.

What it helps with

  • find a plugin that is installed but disabled
  • compare installed_plugins.json with settings.json
  • refresh a stale marketplace cache
  • validate .claude-plugin/marketplace.json
  • enable every installed plugin from a marketplace

Example prompts for the agent

  • Check why an installed plugin does not appear in the available skills.
  • Run python3 scripts/diagnose_plugins.py and explain each problem it finds.
  • Compare enabledPlugins with installed_plugins.json and suggest the fix.

How to install claude-skills-troubleshooting

1Skills CLI (Vercel)

npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a claude-code

2Manually: put the files in place

~/.claude/skills/claude-skills-troubleshooting/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/claude-skills-troubleshooting/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about claude-skills-troubleshooting

How do I install claude-skills-troubleshooting in Claude Code?

Run npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a claude-code. Then check ~/.claude/skills/claude-skills-troubleshooting/SKILL.md.

What does claude-skills-troubleshooting do?

It diagnoses plugin installation, registration, and activation problems in Claude Code. The checks cover settings, marketplace cache metadata, and the records for installed and enabled plugins.

When is a plugin active in Claude Code?

It must be registered in installed_plugins.json and have a true value in settings.json under enabledPlugins. An installation record alone is insufficient.

Source text

SKILL.md · MIT
---
name: claude-skills-troubleshooting
disable-model-invocation: true
description: 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", "skill not showing", "installed but disabled", or "enabledPlugins" issues.
---

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

```bash
python3 scripts/diagnose_plugins.py
```

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:**
```bash
# 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:**
```bash
# 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
```

**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:

```bash
# Reinstall from the config dir owning the real file
CLAUDE_CONFIG_DIR=~/.claude claude plugin install plugin-name@marketplace-name

# Then confirm
claude plugin list
```

### 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:**
```bash
# 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!
   ```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

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

```bash
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

© daymade · MIT · daymade/claude-code-skills

Similar skills

All skills for Agent setup: memory, context, orchestration →

From the same set102

The whole set →
llm-icon-finder llm-icon-finder — a Claude Code skill that pulls AI model and provider icons from the lobe-icons library. Builds CDN URLs for SVG, PNG and WEBP files, downloads them with curl when asked. CX Codex +1 1,000installs video-comparer video-comparer — a skill that compares two videos and builds an HTML report with PSNR and SSIM metrics plus frame-by-frame before/after views. CX Codex +1 1,000installs github-contributor github-contributor is a Claude Code skill that guides contributions to repositories you don’t maintain, from project rules to PR preparation. It activates for requests to fix an upstream issue, open a PR, rebase, or answer a bot review. CX Codex +1 1,000installs teams-channel-post-writer teams-channel-post-writer writes educational Teams channel posts about Claude: feature walkthroughs, tips, prompt examples and principles like context engineering. CX Codex +1 999installs repomix-safe-mixer The repomix-safe-mixer skill scans a project for hardcoded keys and tokens and blocks repomix from packing until the secrets are gone. CX Codex +1 974installs financial-data-collector financial-data-collector pulls real financial data for US public companies from yfinance and hands back structured JSON for DCF, comps and earnings work. CX Codex +1 946installs doc-to-markdown doc-to-markdown is a Claude Code skill that converts DOCX, PDF, PPTX, and saved HTML to Markdown with automated cleanup. It activates on prompts to convert or parse documents. CX Codex +1 945installs repomix-unmixer repomix-unmixer extracts packed Repomix repositories back into original file trees. Useful when inspecting or unpacking projects bundled into single XML, Markdown, or JSON files. CX Codex +1 945installs

Project sponsors

Companies that keep this analytics open