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
npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a claude-codeWhat 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.jsonwithsettings.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.pyand explain each problem it finds. - Compare
enabledPluginswithinstalled_plugins.jsonand 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-code2Manually: put the files in place
~/.claude/skills/claude-skills-troubleshooting/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/claude-skills-troubleshooting/
1Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a codex2Manually: put the files in place
.agents/skills/claude-skills-troubleshooting/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a cursor2Manually: put the files in place
.cursor/skills/claude-skills-troubleshooting/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install daymade/claude-code-skills daymade-claude-code/claude-skills-troubleshooting/SKILL.md2Manually: put the files in place
.github/skills/claude-skills-troubleshooting/SKILL.md1Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a gemini-cli2Platform CLI
gemini skills install https://github.com/daymade/claude-code-skills --path daymade-claude-code/claude-skills-troubleshootingManually: put the files in place
.devin/skills/claude-skills-troubleshooting/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
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