全部技能 / 基础工具与工作流 / claude-skills-troubleshooting
基础工具与工作流 · daymade/claude-code-skills

claude-skills-troubleshooting

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.

风险提醒：黄色 · 留意使用AI 侦查报告
作者 daymadeGitHub daymade/claude-code-skills ↗Stars 1385许可 MIT（仓库根 LICENSE：Copyright (c) 2025 daymade；GitHub API spdx MIT）commit d5c4678cb5
agent 宿主通常会约束 skill 执行权限；风险提醒为 AI 侦查观点，不构成质量或安全保证。第三方 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外部依赖

类型依赖
clipython3
cliclaude（官方 CLI：plugin enable/disable/install/uninstall/marketplace update）
clijq（诊断命令参考中读 JSON）
networkGitHub（issue 引用与 marketplace 内容源）

4风险提醒 风险提醒：黄色 · 留意使用

风险提醒：黄色 · 留意使用
  • 状态模型依赖特定 Claude Code 版本行为 — issue 驱动的结论（如 installed 与 enabled 分离、known_marketplaces 结构）随官方版本演进可能过时；known_issues.md 是静态快照需人工更新
  • 整文件回写 settings.json — enable_all 用 json.load→改→json.dump 回写整个 settings.json；若文件含 env 明文 token 或复杂注释/格式，回写有格式归一化与并发覆盖风险（建议先备份）
  • 文档建议 rm -rf 清 marketplace cache — Issue 3 解法含 rm -rf ~/.claude/plugins/cache/<mkt> 再 update——属用户手动执行、可重建目录，但仍是破坏性命令，agent 执行前应确认
  • 网络动作由官方 CLI 代行 — claude plugin marketplace update 会访问已注册 marketplace（通常 GitHub）；对未审查 marketplace 的信任等同对插件源的信任
风险提醒：黄色，留意使用。自带脚本纯本地：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 环境使用。
    安装 agent 直装可复制
    ① 本站镜像 更新 2026-09-09
    方式 A · 人下载镜像包下载 claude-skills-troubleshooting.tar.gz
    sha256: 3f56dc20d44cb7a1…
    方式 B · JSON 格式安装指南，复制给 agent
    安装指南
    agent 读 JSON 指南后会自动从本站下载安装，无需更多说明。
    ② 上游 GitHub · 原始来源
    能访问 GitHub？直接去上游安装（实时版，可能已更新）GitHub 原始 ↗
    本页镜像锁定 commit d5c4678cb5；上游为实时仓库。
    来源信息 GitHub 原始
    作者 / 仓库daymade / daymade/claude-code-skills
    原始 GitHubdaymade/claude-code-skills ↗
    Stars1385
    最近推送2026-09-09
    本 skill commitd5c4678cb5
    许可MIT（仓库根 LICENSE：Copyright (c) 2025 daymade；GitHub API spdx MIT）
    本站信息
    收录日期2026-09-06
    分类基础工具与工作流
    侦查报告2026-09-06 · 2 遍
    本站镜像与 GitHub 原始是不同来源：本站锁定 commit 快照经 /r2 分发；GitHub 为实时上游，内容可能已更新。