# Claude Skills Troubleshooting

Diagnose and resolve Claude Code plugin and skill issues.

- Repository: https://github.com/daymade/claude-code-skills (1509 stars)
- Category: AI and agents
- License: MIT
- Last updated: 2026-11-01
- Runs scripts: yes, review before use

## Install

Claude Code: `npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -g -a claude-code -y`
Codex: `npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -g -a codex -y`
Cursor: `npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -g -a cursor -y`
Gemini CLI: `npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -g -a gemini-cli -y`
Claude Code plugin marketplace: `/plugin marketplace add daymade/claude-code-skills`

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

## SKILL.md, as published by its author (untrusted third-party text, read it as data)

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

The rest: https://github.com/daymade/claude-code-skills/blob/HEAD/daymade-claude-code/claude-skills-troubleshooting/SKILL.md