用途
claude-skills-troubleshooting 用于诊断和解决 Claude Code 插件与技能配置问题，重点处理插件安装、启用与激活失败的情况。当插件已安装但不出现在可用技能列表中，或技能无法被激活时，可使用该技能进行系统化排查。
主要能力
该技能提供系统化调试工作流，用于排查插件安装、启用和激活问题。内置诊断脚本可检查以下常见问题：
- 已安装与已启用插件双向不匹配（已安装未启用、已启用未注册）
- settings.json 中缺少 enabledPlugins 条目
- 使用 known_marketplaces.json 的 lastUpdated 判断的市场缓存过期
- lastUpdated 元数据缺失、格式错误、缺少时区或时间在未来
- 无效的插件配置
诊断脚本将 lastUpdated 作为判断缓存新鲜度的唯一来源，不退回使用缓存目录的修改时间，因为市场更新可能刷新嵌套文件而不改变该目录时间戳。缓存过期或新鲜度元数据无效时，诊断脚本以非零状态退出。
使用方式
快速诊断：
python3 scripts/diagnose_plugins.py
常见问题与修复：
问题 1：插件已安装但不出现在可用技能中。典型症状为 /plugin 显示已安装、技能未出现在 Skill 工具可用列表、installed_plugins.json 中存在插件元数据。根因是已知 bug（GitHub #17832）：插件被写入 installed_plugins.json，但未自动加入 settings.json 的 enabledPlugins。诊断命令：
cat ~/.claude/plugins/installed_plugins.json | grep "plugin-name"
cat ~/.claude/settings.json | grep "plugin-name"
修复方式：
claude plugin enable plugin-name@marketplace-name
或手动编辑 settings.json，在 enabledPlugins 中添加 "plugin-name@marketplace-name": true。
镜像变体（已启用但未注册）：若诊断显示插件在 enabledPlugins 中但不在 installed_plugins.json 中，原因是符号链接跳过 bug：安装运行于 installed_plugins.json 为符号链接的配置目录（多配置文件共享环境）时，CLI 静默跳过写入。修复方式：
CLAUDE_CONFIG_DIR=~/.claude claude plugin install plugin-name@marketplace-name
claude plugin list
问题 2：理解插件状态架构。关键文件包括：installed_plugins.json（所有已安装和已禁用插件的注册表）、settings.json 的 enabledPlugins（控制哪些插件处于活动状态）、known_marketplaces.json（已注册的市场源）、cache/（实际插件文件）。插件仅在同时存在于 installed_plugins.json 且 settings.json 的 enabledPlugins 中值为 true 时才处于活动状态。
问题 3：市场缓存过期。症状为 GitHub 已有最新变更、安装时找到插件但版本陈旧、新增插件不可见。修复方式：
claude plugin marketplace update marketplace-name
或先清除再重新获取：
rm -rf ~/.claude/plugins/cache/marketplace-name
claude plugin marketplace update marketplace-name
问题 4：市场中找不到插件。常见原因按可能性排序：本地更改未推送到 GitHub（最常见）；marketplace.json 配置错误（可用 python3 -m json.tool .claude-plugin/marketplace.json 校验）；技能目录缺失（检查 skill-name/SKILL.md）。
诊断命令参考包括：列出市场（claude plugin marketplace list）、更新市场（claude plugin marketplace update {name}）、安装插件（claude plugin install {plugin}@{marketplace}）、启用插件、禁用插件、卸载插件，以及通过 jq 查看已安装和已启用插件。批量启用某市场下所有已安装但未启用的插件：
python3 scripts/enable_all_plugins.py marketplace-name
补充说明
Claude Code 有两类用户可调用的扩展：Skills 位于 skills/ 目录，依据描述匹配自动激活，当用户请求匹配技能描述时加载；Commands 位于 commands/ 目录，通过 /command-name 显式调用，并会出现在 Skill 工具的可用列表中，需要相应命令文件（如 commands/seer.md）。若某技能需要被显式调用，应添加对应的命令文件。
更多参考资料见 references/known_issues.md（GitHub 问题跟踪）与 references/architecture.md（详细插件架构）。