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:

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