Back to Details

claude-skills-troubleshooting

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Claude Skills Troubleshooting

Claude Skills 故障排查

Overview

概述

Diagnose and resolve common Claude Code plugin and skill configuration issues. This skill provides systematic debugging workflows for plugin installation, enablement, and activation problems.
诊断并解决Claude Code插件与技能配置的常见问题。此Skill提供了针对插件安装、启用和激活问题的系统化调试流程。

Quick Diagnosis

快速诊断

Run the diagnostic script to identify common issues:
bash
python3 scripts/diagnose_plugins.py
The script checks:
  • Installed vs enabled plugins mismatch
  • Missing enabledPlugins entries in settings.json
  • Stale marketplace cache
  • Invalid plugin configurations
运行诊断脚本以识别常见问题：
bash
python3 scripts/diagnose_plugins.py
该脚本会检查：
  • 已安装插件与已启用插件不匹配的情况
  • settings.json中缺少enabledPlugins条目
  • 市场缓存过期
  • 无效的插件配置

Common Issues

常见问题

Issue 1: Plugin Installed But Not Showing in Available Skills

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

Symptoms:
  • /plugin
    shows plugin as installed
  • Skill not appearing in Skill tool's available list
  • Plugin metadata exists in 
    installed_plugins.json
Root Cause: Known bug (GitHub #17832) - plugins are added to 
installed_plugins.json
but NOT automatically added to 
enabledPlugins
in 
settings.json
.
Diagnosis:
bash
undefined
症状：
  • /plugin
    命令显示插件已安装
  • 技能未出现在Skill工具的可用列表中
  • 插件元数据存在于
    installed_plugins.json
    中
根本原因： 已知Bug（GitHub #17832）- 插件被添加到
installed_plugins.json
但未自动添加到
settings.json
的
enabledPlugins
中。
诊断步骤：
bash
undefined

Check if plugin is in installed_plugins.json

检查插件是否在installed_plugins.json中

cat ~/.claude/plugins/installed_plugins.json | grep "plugin-name"
cat ~/.claude/plugins/installed_plugins.json | grep "plugin-name"

Check if plugin is enabled in settings.json

检查插件是否在settings.json中启用

cat ~/.claude/settings.json | grep "plugin-name"

**Solution:**
```bash
cat ~/.claude/settings.json | grep "plugin-name"

**解决方法：**
```bash

Option 1: Use CLI to enable

选项1：使用CLI启用

claude plugin enable plugin-name@marketplace-name
claude plugin enable plugin-name@marketplace-name

Option 2: Manually edit settings.json

选项2：手动编辑settings.json

Add to enabledPlugins section:

添加到enabledPlugins部分：

"plugin-name@marketplace-name": true

"plugin-name@marketplace-name": true

undefined
undefined

Issue 2: Understanding Plugin State Architecture

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

Key files:
FilePurpose
~/.claude/plugins/installed_plugins.json
Registry of ALL plugins (installed + disabled)
~/.claude/settings.json
→ 
enabledPlugins
Controls which plugins are ACTIVE
~/.claude/plugins/known_marketplaces.json
Registered marketplace sources
~/.claude/plugins/cache/
Actual plugin files
A plugin is active ONLY when:
  1. Exists in 
    installed_plugins.json
    (registered)
  2. Listed in 
    settings.json
    → 
    enabledPlugins
    with value 
    true
关键文件：
文件用途
~/.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

Issue 3: Marketplace Cache Stale

问题3：市场缓存过期

Symptoms:
  • GitHub has latest changes
  • Install finds plugin but gets old version
  • Newly added plugins not visible
Solution:
bash
undefined
症状：
  • GitHub上有最新更改
  • 安装时能找到插件但获取的是旧版本
  • 新添加的插件不可见
解决方法：
bash
undefined

Update marketplace cache

更新市场缓存

claude plugin marketplace update marketplace-name
claude plugin marketplace update marketplace-name

Or clear and re-fetch

或清除后重新获取

rm -rf ~/.claude/plugins/cache/marketplace-name claude plugin marketplace update marketplace-name
undefined
rm -rf ~/.claude/plugins/cache/marketplace-name claude plugin marketplace update marketplace-name
undefined

Issue 4: Plugin Not Found in Marketplace

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

Common causes (in order of likelihood):
  1. Local changes not pushed to GitHub - Most common!
    bash
    git status
git push
claude plugin marketplace update marketplace-name
  2. marketplace.json configuration error
    bash
    python3 -m json.tool .claude-plugin/marketplace.json
  3. Skill directory missing
    bash
    ls -la skill-name/SKILL.md
常见原因（按可能性排序）：
  1. 本地更改未推送到GitHub - 最常见！
    bash
    git status
git push
claude plugin marketplace update marketplace-name
  2. marketplace.json配置错误
    bash
    python3 -m json.tool .claude-plugin/marketplace.json
  3. 技能目录缺失
    bash
    ls -la skill-name/SKILL.md

Diagnostic Commands Reference

诊断命令参考

PurposeCommand
List marketplaces
claude plugin marketplace list
Update marketplace
claude plugin marketplace update {name}
Install plugin
claude plugin install {plugin}@{marketplace}
Enable plugin
claude plugin enable {plugin}@{marketplace}
Disable plugin
claude plugin disable {plugin}@{marketplace}
Uninstall plugin
claude plugin uninstall {plugin}@{marketplace}
Check installed
cat ~/.claude/plugins/installed_plugins.json | jq '.plugins | keys'
Check enabled
cat ~/.claude/settings.json | jq '.enabledPlugins'
用途命令
列出市场
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'

Batch Enable Missing Plugins

批量启用缺失的插件

To enable all installed but disabled plugins from a marketplace:
bash
python3 scripts/enable_all_plugins.py marketplace-name
要启用某个市场中所有已安装但未启用的插件：
bash
python3 scripts/enable_all_plugins.py marketplace-name

Skills vs Commands Architecture

Skills与Commands架构

Claude Code has two types of user-invocable extensions:
  1. Skills (in 
    skills/
    directory)
    • Auto-activated based on description matching
    • Loaded when user request matches skill description
  2. Commands (in 
    commands/
    directory)
    • Explicitly invocable via 
      /command-name
    • Appears in Skill tool's available list
    • Requires command file (e.g., 
      commands/seer.md
      )
If a skill should be explicitly invocable, add a corresponding command file.
Claude Code有两种类型的用户可调用扩展：
  1. Skills（位于
    skills/
    目录）
    • 根据描述匹配自动激活
    • 当用户请求匹配技能描述时加载
  2. Commands（位于
    commands/
    目录）
    • 通过
      /command-name
      显式调用
    • 出现在Skill工具的可用列表中
    • 需要命令文件（例如
      commands/seer.md
      ）
如果希望某个技能可被显式调用，请添加对应的命令文件。

References

参考资料

  • See 
    references/known_issues.md
    for GitHub issue tracking
  • See 
    references/architecture.md
    for detailed plugin architecture
  • 查看
    references/known_issues.md
    以跟踪GitHub问题
  • 查看
    references/architecture.md
    以了解详细的插件架构