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

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"

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

Option 2: Manually edit settings.json

选项2：手动编辑settings.json

Add to enabledPlugins section:

添加到enabledPlugins部分：

"plugin-name@marketplace-name": true

undefined

undefined

Issue 2: Understanding Plugin State Architecture

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

Key files:

File	Purpose
`~/.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:

Exists in
```
installed_plugins.json
```
(registered)
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/`	实际插件文件

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

存在于
```
installed_plugins.json
```
中（已注册）
在
```
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

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):

Local changes not pushed to GitHub - Most common!

bash

git status
git push
claude plugin marketplace update marketplace-name

marketplace.json configuration error

bash

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

Skill directory missing
bash
```
ls -la skill-name/SKILL.md
```

常见原因（按可能性排序）：

本地更改未推送到GitHub - 最常见！

bash

git status
git push
claude plugin marketplace update marketplace-name

marketplace.json配置错误

bash

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

技能目录缺失
bash
```
ls -la skill-name/SKILL.md
```

Diagnostic Commands Reference

诊断命令参考

Purpose	Command
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:

Skills (in
```
skills/
```
directory)
- Auto-activated based on description matching
- Loaded when user request matches skill description
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有两种类型的用户可调用扩展：

Skills（位于
```
skills/
```
目录）
- 根据描述匹配自动激活
- 当用户请求匹配技能描述时加载
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
```
以了解详细的插件架构