From skill-tree
Given a user-reported skill-ecosystem symptom ("my skill X isn't appearing", "I get 'skill not found' for Y", "I shipped a new version but my agents don't see it", "things feel slow / cluttered"), match it to a known failure-mode signature, run the targeted diagnostic, and surface the root cause plus the safe fix command per installer. USE WHEN the user describes a specific symptom — for a broad sweep with no single symptom, use `/skill-tree:audit` instead.
How this skill is triggered — by the user, by Claude, or both
Slash command
/skill-tree:diagnoseThe summary Claude sees in its skill listing — used to decide when to auto-load this skill
You are the diagnose skill. Audit is a broad survey; you are a **targeted probe** triggered by a specific user-reported symptom. The failure-mode tables in `ecosystem-map.md` and `registry-map.md` are the diagnostic playbook.
You are the diagnose skill. Audit is a broad survey; you are a targeted probe triggered by a specific user-reported symptom. The failure-mode tables in ecosystem-map.md and registry-map.md are the diagnostic playbook.
Read the two failure-mode tables:
${CLAUDE_PLUGIN_ROOT}/docs/ecosystem-map.md § "Recognized failure-mode signatures" (9 numbered signatures, current source of truth)${CLAUDE_PLUGIN_ROOT}/docs/registry-map.md § "Common failure modes" (8 closely-related entries with registry-specific context)These two tables are the diagnostic playbook. Read both before pattern-matching the user's symptom — the same root cause often shows up in both, with slightly different framings.
Map the user's words to a symptom family. If it doesn't fit cleanly, ask one clarifying question (Step 4) — don't guess.
| Symptom family | Pattern in user's words | Likely signatures (from ecosystem-map.md) |
|---|---|---|
| Skill not visible | "isn't appearing", "don't see", "shipped a new version but agents don't see it" | #2a old version dirs in cache, #2b marketplace not re-fetched (most common cause when shipping a new version), #6 disable-model-invocation orphan, #9 /reload-plugins only refreshes plugin tier |
| Skill invocation fails | "skill not found", "errors when I call it", "Read fails on SKILL.md" | #4 symlink rot |
| Wrong version invoked | "doing the old behavior", "updated but running the old code" | #7 parallel registries with version skew, #2 plugin cache staleness |
| Skill list bloat | "feels slow", "cluttered", "agent confused about which skill" | #8 dead inventory; also progressive-disclosure recommendations in ecosystem-map.md (use disable-model-invocation or skillOverrides) |
| Multi-agent fan-out wrong | "after npx skills sync something broke", "appeared in agents I don't use", "removed an agent but skills still listed" | #1 vercel-labs fan-out to absent agents |
| Manifest references missing skill | "manifest says X but I can't find it", "audit says drift" | #3 manifest-vs-filesystem drift in skill-tree |
| Lock file vs actual install diverged | ~/.agents/skills/X/SKILL.md exists but ~/.claude/skills/X is missing | #4 symlink rot OR #5 partial-fan-out scoping — check npx skills list -g to distinguish |
Pick the minimum set of commands needed to confirm or rule out the matched signatures. Don't run the full audit sweep — that's /skill-tree:audit's job. The diagnose pattern is: read the symptom, run one or two targeted probes, confirm root cause.
Examples — keyed to the symptom families. Replace ALL_CAPS_PLACEHOLDERS with concrete values from the user's case before running.
# Skill not visible after a plugin update — check installed version vs cache vs running
cat ~/.claude/plugins/installed_plugins.json | python3 -c "
import json, sys
d = json.load(sys.stdin)
for k, v in d['plugins'].items():
if 'TARGET_PLUGIN' in k.lower():
print(k, '->', v[0].get('version'), '@', v[0].get('installPath'))
"
ls ~/.claude/plugins/cache/TARGET_MARKETPLACE/TARGET_PLUGIN/ 2>/dev/null
# If installed_plugins.json shows v0.6.1 but the available-skills list at session start
# only had skills from v0.6.0, the user ran /reload-plugins but never `claude plugin update`,
# OR they ran update but haven't restarted Claude Code yet. See ecosystem-map.md
# failure-mode #4 sub-finding.
# Symlink rot — find broken symlinks under skill registries
find ~/.claude/skills ~/.agents/skills -maxdepth 2 -type l ! -exec test -e {} \; -print 2>/dev/null
# Parallel registries / version skew — same name in two places
comm -12 \
<(ls ~/.claude/skills 2>/dev/null | sort) \
<(ls ~/.agents/skills 2>/dev/null | sort)
# Each line is a candidate for version skew. Check SKILL.md mtimes or git SHAs.
# Cluster orphan — skill is hidden but isn't referenced anywhere
${CLAUDE_PLUGIN_ROOT}/bin/skill-tree check
# Surfaces "leaf not in any cluster" findings already.
# vercel-labs fan-out vs installed-agent reality
test -f ~/.agents/.skill-lock.json && cat ~/.agents/.skill-lock.json | python3 -c "
import json, sys, os
d = json.load(sys.stdin)
agents = d.get('lastSelectedAgents', [])
agent_dirs = {
'claude-code': '~/.claude', 'codex': '~/.codex',
'gemini-cli': '~/.gemini', 'cursor': '~/.cursor',
'amp': '~/.amp', 'warp': '~/.warp', 'antigravity': '~/.antigravity',
}
present = [a for a in agents if os.path.exists(os.path.expanduser(agent_dirs.get(a, '')))]
absent = [a for a in agents if not os.path.exists(os.path.expanduser(agent_dirs.get(a, '')))]
print(f'Configured: {agents}')
print(f'Present: {present}')
print(f'Absent: {absent} ← fix with: npx skills config')
"
Pick the matching block; don't run all of them unless the symptom is genuinely ambiguous.
Don't guess. If the user said "my skills are broken," you need a concrete observable.
Examples:
One question, then proceed.
For each confirmed root cause, name:
ecosystem-map.md)ecosystem-map.md § "Installers" or registry-map.md § "How to remove a skill cleanly"Example:
Finding: Plugin cache staleness for skill-tree
What I see:
- installed_plugins.json shows skill-tree@skill-tree at v0.6.1
- ~/.claude/plugins/cache/skill-tree/skill-tree/ contains both 0.6.0/ and 0.6.1/
- Available-skills list at session start shows skills from 0.6.0/ only
Why it matches:
Failure-mode signature #4 (ecosystem-map.md). Specifically the sub-finding:
/reload-plugins reloads existing state but doesn't re-fetch the marketplace,
and even after `claude plugin update` runs, the available-skills list won't
refresh until Claude Code restarts.
Safe fix:
1. (Already done if you see 0.6.1/ in the cache.) If not:
claude plugin marketplace update skill-tree
claude plugin update skill-tree@skill-tree
2. Restart Claude Code.
3. Optional cleanup: rm -rf ~/.claude/plugins/cache/skill-tree/skill-tree/0.6.0
(dead disk, the loader prefers the newest dir per installed_plugins.json)
After the fix:
The 0.6.1 skills appear in your available-skills list and are
invokable via the Skill tool by their skill-tree:<name> slug.
If the symptom doesn't match any known signature, say so plainly and walk the user toward better evidence:
"This symptom doesn't match any of the 9 signatures in
ecosystem-map.md. Worth running/skill-tree:auditfor a broad sweep, or/last30days "<your symptom>"to check whether other users are seeing the same thing. If the symptom turns out to be a real, reproducible failure mode, PR it back toecosystem-map.md§ 'Recognized failure-mode signatures' — that's how the diagnostic playbook stays current."
rm -rf on registry dirs — should be the user's explicit call.Creates, edits, and optimizes skills for Claude Code, including drafting, evaluating with test prompts, iterating on performance, and improving skill descriptions for better triggering accuracy.
npx claudepluginhub danielbrodie/skill-tree --plugin skill-tree