Workflow & Core Tools · daymade/claude-code-skills

claude-skills-troubleshooting

Name: claude-skills-troubleshooting
Author: daymade/claude-code-skills

Diagnose and resolve Claude Code plugin and skill issues. This skill should be used when plugins are installed but not showing in available skills list, skills are not activating as expected, or when troubleshooting enabledPlugins configuration in settings.json. Triggers include "plugin not working", "skill not showing", "installed but disabled", or "enabledPlugins" issues.

L4 High-Privilege · Graded auth & full auditV1 Commit-PinnedExecute CommandNetwork AccessWrite FileDual-pass Audit

Control levels describe skill capabilities and suggested control measures; they do not represent quality or safety certifications, nor do they dictate usability. Usage decisions rest entirely with users and administrators. Different agent hosts apply varying constraints; do not assume hosts provide automatic protection. Third-party skill copyrights belong to their original authors. Use at your own risk.

1How It Works & Mechanism

Run diagnostic scripts first for deterministic troubleshooting: diagnose_plugins.py reads local ~/.claude plugin state files (installed_plugins.json, enabledPlugins in settings.json, and known_marketplaces.json), compares the list of 'installed but not enabled' plugins, and checks cache freshness.

daymade-claude-code/claude-skills-troubleshooting/SKILL.md

Run the diagnostic script to identify common issues: ```bash python3 scripts/diagnose_plugins.py

The script is strictly read-only: it prints its findings after loading the three configuration files via json.load; exit codes are semantic (returns 1 on issues).

Core diagnostic criterion: Uses lastUpdated from known_marketplaces.json as the single source of truth for freshness (strict ISO-8601 parsing with timezone; missing, malformed, non-timezone, or future timestamps are treated as invalid) without relying on cache directory mtime.

daymade-claude-code/claude-skills-troubleshooting/scripts/diagnose_plugins.py

never guess freshness from the unreliable cache-directory mtime.

Parsing restricts timezones to Z or ±HH:MM via regex and normalizes to UTC; entries older than STALE_AFTER=7 days are deemed stale, and future timestamps are deemed invalid.

Two-tier remediation path: Uses the official CLI (claude plugin enable/disable/update) and direct edits to enabledPlugins in settings.json; also provides a batch enablement script enable_all_plugins.py (matches by marketplace suffix with interactive confirmation prior to write).

daymade-claude-code/claude-skills-troubleshooting/SKILL.md

claude plugin enable plugin-name@marketplace-name

Batch script enable_all_plugins.py: Loads installed_plugins.json and settings.json, lists pending items to be enabled, and only writes enabledPlugins[k]=true back after an input('[y/N]') confirmation.

Knowledge base support: references/architecture.md details the plugin lifecycle and activation flow (install → copy to cache → register → manually enable → read enabledPlugins on startup), references/known_issues.md tracks upstream GitHub issues (#17832, etc.), and SKILL.md embeds root causes and resolutions for 4 Common Issues.

daymade-claude-code/claude-skills-troubleshooting/references/known_issues.md

https://github.com/anthropics/claude-code/issues/17832

Issue #17832 (installed plugins are not auto-enabled) serves as the direct evidence for the root cause of Issue 1; known_issues.md also tracks #19696/#17089/#13543/#16260.

Architectural clarification between 'Skill vs Command extensions': skills/ are automatically matched and activated by description, while commands/ require explicit invocation via /command-name; explicit invocation requires adding a command file.

daymade-claude-code/claude-skills-troubleshooting/SKILL.md

If a skill should be explicitly invocable, add a corresponding command file.

This is a critical branch of attribution when investigating 'installed skill does not trigger': a skill being visible in the Skill tool but not matched vs being completely disabled are two distinct issues.

2Core Capabilities

01Deterministic diagnosis of installed vs enabled mismatches (lists installed but disabled plugins and provides enable commands)

02Marketplace cache freshness inspection: lastUpdated validation (timezone/future date/missing checks) + 7-day expiration check + non-zero exit code

03Batch-enable all installed but disabled plugins for a specific marketplace (with pre-write y/N confirmation)

04Plugin architecture quick reference: active status criteria (dual requirements: registration in installed_plugins.json + enabledPlugins=true)

05Guidance on differences between skill and command, including explicit invocable entrypoints (commands/ files)

06Upstream issue tracking and related document indexing (known_issues.md / architecture.md)

3External Dependencies

Kind	Dependency / Endpoint
cli	python3
cli	claude（官方 CLI：plugin enable/disable/install/uninstall/marketplace update）
cli	jq（诊断命令参考中读 JSON）
network	GitHub（issue 引用与 marketplace 内容源）

4Recommended Governance & Evidence

Suggested Controls for Safe Operation

For Agent Runtime

Graded/per-use authorization, sandbox recommended

For Administrators

Approval workflow, rollback support, full audit

Evidence & Triggers (File Paths & Excerpts)

scripts/: Executes local scripts or commands: scripts/diagnose_plugins.py
网络端点: Declares external network access: (User action guided by SKILL) claude plugin marketplace update — official CLI fetches from registered marketplaces
本地工作目录: File I/O and artifact output: enabledPlugins in ~/.claude/settings.json (only rewritten after interactive confirmation via enable_all_plugins.py)

Audit Notes: Included scripts are purely local: diagnose only reads three configuration files under ~/.claude; enable_all writes to enabledPlugins in settings.json only after interactive confirmation (y/N)—if this file contains plaintext env tokens, reading/modifying/rewriting accesses secret-bearing files (an attack surface exists, but the script does not touch secret fields). Remediations guided by SKILL include official claude CLI marketplace updates (outbound requests to registered marketplaces/GitHub, predictable targets) and cache directory clearing (rm -rf, manual user action, fully rebuildable). Documentation also references GitHub issue links. Contains no custom network code or credential extraction logic.

5Second-Pass Verification

[ok] 无网络外发（脚本层） — 两脚本零网络；https 只出现在 SKILL/known_issues 文档链接
[ok] diagnose 只读声明属实 — 全文仅 json.load + print，无写文件路径
[ok] enable_all 写前确认属实 — 写入前 input("Enable all these plugins? [y/N] ")，非 y 即取消
[ok] lastUpdated 唯一新鲜度来源规则三方一致 — SKILL.md / architecture.md / diagnose_plugins.py 同口径（时区必需、mtime 不可信、7 天过期、未来时间戳无效）
[ok] 诊断退出码语义 — main() 末尾 missing/stale/invalid 任一成立打印 Action needed 并 return 1，与 SKILL 'exits nonzero' 一致
[ok] settings.json 含密钥时的接触面 — enable_all 整文件 json.load/json.dump 回写；密钥字段原样保留不处理——按统一分档‘接触即 orange’上浮边界，本档定 yellow 因脚本从不读取/传递密钥字段，reason 已注明触发条件

6Verdict & Scenarios

Prioritizes mechanical diagnosis with clear root-cause identification (official bug #17832), turning 'installed but not showing' from guesswork into verifiable state checks

Hardcodes freshness criteria to lastUpdated (including timezone/future timestamp validation), which is much more reliable than directory mtime

Well-structured runbook: Quick Diagnosis → Common Issues → Command Cheat Sheet, allowing agents to navigate directly by symptoms

Destructive or modifying remediations (clearing cache, batch enablement) include confirmation prompts or follow official CLI paths

Best for: Ideal for Claude Code users needing systematic troubleshooting when 'plugins are installed but not showing / skills do not activate / enabledPlugins has configuration issues / cache is stale'; also suitable for maintainers looking to batch-enable all plugins from a marketplace (script + confirmation) or understand the plugin enablement mechanism.

Not for: Not suitable for failures unrelated to the Claude Code plugin system (general runtime errors, generic network or permission issues); not meant to be used as a 'magic fix' script (it only diagnoses and batch-enables; other fixes must follow official CLI workflows); not suitable for environments lacking ~/.claude configuration or pure Codex environments.

Install Agent-Ready

① Verified Mirror 2026-09-09

Option A · Direct DownloadDownload claude-skills-troubleshooting.tar.gz

sha256: 3f56dc20d44cb7a1…

Option B · Copy Guide for Agent

install.json

Agents automatically download and verify mirrors from this JSON guide.

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.