基础工具与工作流 · 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 高权限 · 分级授权与审计V1 已固定执行命令联网读写文件Dual-pass Audit

管控等级描述 skill 的能力与建议配套的管控措施，不代表质量或安全认证，也不表示可用或不可用。是否使用由用户和管理者决定。不同 agent 宿主对权限的约束各不相同，请勿假定宿主一定会提供安全兜底。第三方 skill 版权归原作者，使用风险由使用者自行承担。

1实现原理 · 为什么它能做到

先跑诊断脚本做机械排查：diagnose_plugins.py 读本地 ~/.claude 插件状态文件（installed_plugins.json、settings.json 的 enabledPlugins、known_marketplaces.json），比对‘已装未启用’清单并检查缓存新鲜度。

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

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

脚本只读不写：json.load 三个配置文件后打印发现；退出码语义化（有问题 return 1）。

诊断核心判据：以 known_marketplaces.json 的 lastUpdated 为唯一新鲜度来源（严格 ISO-8601 带时区解析，缺失/畸形/无时区/未来时间戳都算无效），不信任 cache 目录 mtime。

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

never guess freshness from the unreliable cache-directory mtime.

parse 用正则限定 Z 或 ±HH:MM 时区并归一化为 UTC；超过 STALE_AFTER=7 天判 stale，未来时间戳判 invalid。

修复路径分两层：官方 CLI（claude plugin enable/disable/update）与直接编辑 settings.json 的 enabledPlugins；并提供批量启用脚本 enable_all_plugins.py（按 marketplace 后缀匹配，写前交互确认）。

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

claude plugin enable plugin-name@marketplace-name

批量脚本 enable_all_plugins.py：先加载 installed_plugins.json 与 settings.json，列出待启用项，经 input('[y/N]') 确认后才把 enabledPlugins[k]=true 写回。

知识库支撑：references/architecture.md 描述插件生命周期与激活流（装→拷 cache→注册→手动 enable→启动读 enabledPlugins），references/known_issues.md 追踪 GitHub 上游 issue（#17832 等），SKILL.md 内嵌 4 个 Common Issues 的根因与解法。

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

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

Issue #17832（装了不自动 enable）是 Issue 1 根因的直接依据；known_issues.md 亦收录 #19696/#17089/#13543/#16260。

对‘Skill 与 Command 两套扩展’做了架构澄清：skills/ 自动按描述匹配激活，commands/ 需 /command-name 显式调用，若要显式可调需补 command 文件。

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

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

这是排查‘装了 skill 却不触发’时的重要归因分支：技能在 Skill tool 可见但不被匹配，与根本未启用是两类问题。

2核心能力

01机械诊断 installed vs enabled 不匹配（列出已装未启用插件并给出 enable 命令）

02marketplace 缓存新鲜度检查：lastUpdated 解析（时区/未来时间/缺失校验）+ 7 天过期判定 + 非零退出码

03批量启用某 marketplace 全部已装未启用插件（写前 y/N 确认）

04插件架构速查：active 判定（installed_plugins.json 注册 + enabledPlugins=true 双条件）

05skill/command 区别与显式可调入口（commands/ 文件）指引

06上游 issue 追踪与相关文档索引（known_issues.md / architecture.md）

3外部依赖

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

4管控建议与判定依据

建议配套管控措施

面向 Agent

分级或逐次授权，建议在沙箱运行

面向管理者

审批流程、可回滚、全程审计

判定依据（文件路径与关键语句摘要）

scripts/: 执行本地脚本或命令: scripts/diagnose_plugins.py
网络端点: 声明外部网络访问: （SKILL 指引的用户动作）claude plugin marketplace update —— 官方 CLI 从已注册 marketplace
本地工作目录: 文件读写与工件输出: ~/.claude/settings.json 的 enabledPlugins（仅 enable_all_plugins.py 交互确认后整文件回写

审计说明： 。自带脚本纯本地：diagnose 只读 ~/.claude 三个配置文件；enable_all 交互（y/N）后写 settings.json 的 enabledPlugins——若该文件含明文 env token，读改写即接触含密钥文件（接触面存在但脚本不触碰密钥字段）。SKILL 指引的修复含官方 claude CLI 的 marketplace 更新（外发到已注册 marketplace/GitHub，对象可预期）与清 cache 目录（rm -rf，用户手动、可重建）。文档还引用 GitHub issue 链接。无自研网络代码、无凭证提取逻辑。

5第二遍独立确认

[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 已注明触发条件

6结论

机械诊断先行 + 明确根因（官方 bug #17832），把‘装了不显示’从玄学变成可验证的状态检查

新鲜度判据写死为 lastUpdated（含时区/未来时间校验），比看目录 mtime 可靠

runbook 结构清晰：Quick Diagnosis → Common Issues → 命令速查表，agent 可按症状直达

破坏性修复（清 cache、批量 enable）都有确认步骤或 CLI 官方路径

适合： 适合 Claude Code 用户遇到‘插件装了不显示/技能不激活/enabledPlugins 配置问题/缓存陈旧’时做系统排查；也适合需要批量启用某 marketplace 全部插件（脚本 + 确认）或想理解插件启用机制的维护者。

不适合： 不适合与 Claude Code 插件体系无关的故障（普通报错、网络、权限等）；不适合把脚本当‘万能修复’——它只诊断与批量启用，其余修复仍需按官方 CLI 流程；也不适合在无 ~/.claude 配置或纯 Codex 环境使用。

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

agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。

② Upstream GitHub

GitHub Repo ↗

Pinned to commit d5c4678cb5.