claude-skills-troubleshooting

Engineering Community

Repo stars 0
Author updated Aug 24, 2026, 03:33 PM
Author repo claude-code-skills

Interpretation is structured for decision-making; original keeps the upstream SKILL.md unchanged.

Decide Fit First

Core job: Diagnose and resolve Claude Code plugin and skill issues. This skill should be used when plugins are installed but not showing i…
Best fit: Use it when the task has reusable inputs, steps, and validation criteria rather than a one-off answer.
Avoid forcing it: If the source lacks commands, platform support, or external-service evidence, keep those fields unknown instead of guessing.

Design Intent

Structure: The skill is organized around “Overview”, “Quick Diagnosis”, “Common Issues”, “Issue 1: Plugin Installed But Not Showing in Available Skills”, showing how the author expects the agent to judge fit, collect context, and produce verifiable output.
Trigger evidence: Prioritize the author’s wording around when to use it, what context to collect, and what output shape to produce.
Evidence boundary: Author text states facts, repository files prove commands and paths, and Fluxly only adds fit, limits, and usage judgment.

How To Use It

Inputs: Provide target material, scope, expected result, forbidden changes, and validation method.
Invocation: Name claude-skills-troubleshooting directly; if the source includes slash commands, start with the command and then add task context.
Validation: Start small and check whether the result follows “Overview / Quick Diagnosis / Common Issues” before expanding.

Boundaries And Review

Dependencies: It usually needs no extra API key, so start with a small validation task.
Permissions: Declared permissions include read / write; ask the agent to state file, command, and rollback boundaries before acting.
Quality bar: A useful result names the deliverable, evidence, and next action. Generic prose means the task needs tighter context.

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:

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) - plugins are added to installed_plugins.json but NOT automatically added to enabledPlugins in settings.json.

Diagnosis:

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

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

Exists in installed_plugins.json (registered)
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:

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

Local changes not pushed to GitHub - Most common!

git status
git push
claude plugin marketplace update marketplace-name

marketplace.json configuration error

python3 -m json.tool .claude-plugin/marketplace.json

Skill directory missing
```
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:

python3 scripts/enable_all_plugins.py marketplace-name

Skills vs Commands Architecture

Claude Code has two types of user-invocable extensions:

Skills (in skills/ directory)
- Auto-activated based on description matching
- Loaded when user request matches skill description
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

Fluxly profile Author and license come from source; runtime, permissions, and network are Fluxly detections or estimates

Fluxly category: 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
Author / version / license: @daymade · no license declared
Fluxly token estimate: Lean
Fluxly setup estimate: Plug-and-play
External API key: No requirement detected
Detected OS requirements: Unspecified
Runtime requirements: Unspecified
Detected file/system behavior: Read-only
Write / modify
Detected network behavior: External requests
Install commands: None (reference only)

Profile is derived at build time from SKILL.md and install vectors. Subject to drift from author intent.

Heads up: 未限定 allowed-tools，默认拥有全部工具权限。

Output preview claude-skills-troubleshooting.preview

The current SKILL.md does not define a fixed output example.

SKILL.md SKILL.md

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

…

Evidence boundary and execution chain

Author text anchors workflow facts; Fluxly only indexes current sections, terms, files, and commands.

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 -> knownmarketplaces.json · lastUpdated · /plugin · installedplugins.json · enabledPlugins · settings.json · ~/.claude/plugins/installedplugins.json · ~/.claude/settings.json
body sha256 -> 8ce25574fb3b