claude-skills-troubleshooting

Claude Skills 故障排查

概述

诊断并解决常见的 Claude Code 插件和技能配置问题。本技能提供系统化的调试工作流，用于排查插件安装、启用和激活问题。

快速诊断

运行诊断脚本，找出常见问题：

python3 scripts/diagnose_plugins.py

脚本会检查：

• 已安装与已启用插件之间的双向不匹配（已安装但未启用，以及已启用但未注册）
• settings.json 中缺少 enabledPlugins 条目
• 使用 known_marketplaces.json 中的 lastUpdated 检查市场缓存是否过期
• 缺失、格式错误、不含时区或时间在未来的 lastUpdated 元数据
• 无效的插件配置

将 lastUpdated 视为唯一的缓存新鲜度依据。不要退而使用缓存目录的修改时间：市场更新可能会刷新嵌套文件，却不会更改该目录的时间戳。缓存过期或新鲜度元数据无效时，诊断会以非零状态码退出。

常见问题

问题 1：插件已安装，但未显示在可用技能中

症状：

• /plugin 显示插件已安装
• 技能未出现在 Skill 工具的可用列表中
• installed_plugins.json 中存在插件元数据

根本原因： 已知错误（GitHub #17832）——插件会被添加到 installed_plugins.json，但不会自动添加到 settings.json 的 enabledPlugins 中。

诊断：

# Check if plugin is in installed_plugins.json
cat ~/.claude/plugins/installed_plugins.json | grep "plugin-name"

# Check if plugin is enabled in settings.json
cat ~/.claude/settings.json | grep "plugin-name"

解决方案：

# Option 1: Use CLI to enable
claude plugin enable plugin-name@marketplace-name

# Option 2: Manually edit settings.json
# Add to enabledPlugins section:
# "plugin-name@marketplace-name": true

镜像情况——已启用但未注册： 如果诊断结果显示插件已列在 enabledPlugins 中，但未列在 installed_plugins.json 中，原因是符号链接跳过错误：安装操作使用了一个配置目录，其中的 installed_plugins.json 是符号链接（多配置文件共享设置），CLI 因此静默跳过了写入。请参阅 references/known_issues.md →“Symlinked installed_plugins.json”。修复方法：

# Reinstall from the config dir owning the real file
CLAUDE_CONFIG_DIR=~/.claude claude plugin install plugin-name@marketplace-name

# Then confirm
claude plugin list

问题 2：了解插件状态架构

关键文件：

文件	用途
~/.claude/plugins/installed_plugins.json	所有插件（已安装和已禁用）的注册表
~/.claude/settings.json → enabledPlugins	控制哪些插件处于激活状态
~/.claude/plugins/known_marketplaces.json	已注册的市场源
~/.claude/plugins/cache/	插件实际文件

插件仅在满足以下条件时才处于激活状态：

1. 存在于 installed_plugins.json 中（已注册）
2. 在 settings.json → enabledPlugins 中列出，且值为 true

问题 3：市场缓存过期

症状：

• GitHub 上已有最新更改
• 安装时能找到插件，但获取的是旧版本
• 新增的插件不可见

解决方案：

# Update marketplace cache
claude plugin marketplace update marketplace-name

# Or clear and re-fetch
rm -rf ~/.claude/plugins/cache/marketplace-name
claude plugin marketplace update marketplace-name

问题 4：在市场中找不到插件

常见原因（按可能性从高到低排序）：

1. 本地更改尚未推送到 GitHub——最常见！

   git status
   git push
   claude plugin marketplace update marketplace-name
   

2. marketplace.json 配置错误

   python3 -m json.tool .claude-plugin/marketplace.json
   

3. 技能目录缺失

   ls -la skill-name/SKILL.md
   

诊断命令参考

用途	命令
列出市场	claude plugin marketplace list
更新市场	claude plugin marketplace update {name}
安装插件	claude plugin install {plugin}@{marketplace}
启用插件	claude plugin enable {plugin}@{marketplace}
禁用插件	claude plugin disable {plugin}@{marketplace}
卸载插件	claude plugin uninstall {plugin}@{marketplace}
检查已安装插件	cat ~/.claude/plugins/installed_plugins.json | jq '.plugins | keys'
检查已启用插件	cat ~/.claude/settings.json | jq '.enabledPlugins'

批量启用缺失插件

启用某个市场中所有已安装但已禁用的插件：

python3 scripts/enable_all_plugins.py marketplace-name

Skills 与 Commands 架构

Claude Code 有两类可由用户调用的扩展：

1. Skills（位于 skills/ 目录中）

   • 根据描述匹配自动激活
   • 用户请求符合技能描述时加载

2. Commands（位于 commands/ 目录中）

   • 通过 /command-name 显式调用
   • 显示在 Skill 工具的可用列表中
   • 需要命令文件（例如 commands/seer.md）

如果某项技能需要支持显式调用，请添加对应的命令文件。

参考资料

• 查看 references/known_issues.md 以跟踪 GitHub 问题
• 查看 references/architecture.md 了解插件架构详情