claude skills troubleshooting
- Repo stars 0
- Author updated Aug 24, 2026, 07:33 AM
- Author repo claude-code-skills
- Domain
- Engineering
- Author-declared agents
- No explicit declaration found; this is not inferred or tested compatibility
- Static check
- 88 / 100 · heuristic scan, not runtime safety proof
- Runtime evidence
- Not run; no isolated runtime test evidence is currently recorded
- Author / version / license
- @daymade · no license declared
- Token usage
- Lean
- Setup complexity
- Plug-and-play
- External API key
- Not required
- Operating systems
- Unspecified (assume cross-platform)
- Runtime requirements
- No explicit requirements detected
- Detected file/system behavior
-
- Read-only
- Write / modify
- Network behavior
- External requests
- Install commands
- None (reference only)
Heads up: Tool permissions are not declared; actual access depends on the runtime.
# 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 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
```
### 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
Sections and files
Listed in source order.
sections -> Overview → Quick Diagnosis → Common Issues → Issue 1: Plugin Installed But Not Showing in Available Skills → Issue 2: Understanding Plugin State Architecture → Issue 3: Marketplace Cache Stale
terms -> Symptoms · Root Cause · Diagnosis · Solution · Key files · A plugin is active ONLY when · Common causes (in order of likelihood) · Local changes not pushed to GitHub
files/cmd -> known_marketplaces.json · lastUpdated · /plugin · installed_plugins.json · enabledPlugins · settings.json · ~/.claude/plugins/installed_plugins.json · ~/.claude/settings.json
body sha256 -> 8ce25574fb3b
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: The script checks: Installed vs enabled plugins mismatch Missing enabledPlugins entries in settings.json Stale marketplace cache using
known_marketplaces.jsonlastUpdatedIssue 1: Plugin Installed But Not Showing in Available Skills
Symptoms:
/pluginshows plugin as installed Skill not appearing in Skill tool's available list Plugin metadata exists ininstalled_plugins.jsonRoot Cause: Known bug (GitHub #17832) - plugins are added toinstalled_plugins.jsonbut NOT automatically added toenabledPluginsinsettings.json.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 sourcesIssue 3: Marketplace Cache Stale
Symptoms: GitHub has latest changes Install finds plugin but gets old version Newly added plugins not visible Solution: