agentsclimarketplace

Diagnose

Skill danielbrodie/skill-tree/skills/diagnose

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.From its SKILL.md

Install
npx -y skills add danielbrodie/skill-tree --skill diagnose

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

One thing to look at

  • 2 stars2 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

9.4 KB, as published. Nobody here has run it

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.

Step 1 — read the docs

Read the two failure-mode tables:

  1. ${CLAUDE_PLUGIN_ROOT}/docs/ecosystem-map.md § "Recognized failure-mode signatures" (9 numbered signatures, current source of truth)
  2. ${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.

Step 2 — classify the symptom

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 familyPattern in user's wordsLikely 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

Step 3 — run the targeted diagnostic

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.

Step 4 — for ambiguous symptoms, ask one clarifying question

Don't guess. If the user said "my skills are broken," you need a concrete observable.

Examples:

  • "What specifically happens — does the skill not appear in the list, or does it appear but error when invoked?"
  • "Did this start after a specific action (plugin update, npx skills sync, agent uninstall)?"
  • "Which agent is showing the problem — Claude Code, Codex, Gemini CLI?"

One question, then proceed.

Step 5 — present the finding

For each confirmed root cause, name:

  • What I see — the concrete evidence with file paths, version numbers, command output
  • Why it matches — which failure-mode signature it corresponds to (cite by number from ecosystem-map.md)
  • Requires host-agent restart? — Y/N. Cache-staleness fixes often need Claude Code / Codex / Gemini CLI to restart before the new state is visible to the running process. Surface this loudly when it applies; don't bury it in the safe-fix block.
  • Safe fix — the right tool's command per ecosystem-map.md § "Installers" or registry-map.md § "How to remove a skill cleanly"
  • What changes after the fix — so the user can verify
  • If partially applied: if the evidence shows the user has already done part of the fix, name what's done and what remains. Don't pretend the diagnostic is starting from a clean slate.

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.

Step 6 — gap report

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:audit for 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 to ecosystem-map.md § 'Recognized failure-mode signatures' — that's how the diagnostic playbook stays current."

Notes

  • Audit vs. diagnose: audit is a sweep — it surveys everything and ranks findings. Diagnose is a probe — it takes a symptom and narrows to one root cause. If the user said "audit my skills" or "what's going on with my setup," they want audit. If they said "X is broken / X isn't working," they want diagnose.
  • Don't auto-apply fixes. Walk the user through the safe action. Some "fixes" — especially rm -rf on registry dirs — should be the user's explicit call.
  • Cite the signature by number. Says "failure-mode #4" gives the user (and any future agent reading the conversation) a stable handle they can look up in the doc.
  • Restart-required findings are legitimate. Sometimes the root cause is "you need to restart the host agent for the new cache to take effect." That's a real fix; surface it explicitly instead of pretending the problem is on-disk only.
  • If the symptom turns out to span two registries (e.g., vercel-labs + Claude Code plugin cache), name both findings. Don't pick one for the user.

Keep looking

Skills are one crate of 609,689. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.