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结论
适合： 适合 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:
Option B · Copy Guide for Agent3f56dc20d44cb7a1…agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
② Upstream GitHub
GitHub Repo ↗
Pinned to commit d5c4678cb5.