claude-skills-troubleshooting

---
name: claude-skills-troubleshooting
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
- 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](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
```

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