克劳德技能故障排除
- 作者仓库星标 0
- 作者更新于 2026年8月24日 07:33
- 作者仓库 claude-code-skills
- 领域
- 工程开发
- 作者声明的智能体
- 未找到明确声明;不据此推断已兼容或已测试
- 静态检查
- 88 / 100 · 启发式扫描,不代表运行安全
- 运行环境证据
- 未执行;当前没有隔离运行测试证据
- 作者 / 版本 / 许可证
- @daymade · 未声明许可证
- 上下文用量评级
- 低消耗
- 接入复杂程度
- 即装即用
- 是否需要外部接口密钥
- 不需要
- 兼容的系统
- 未声明(默认跨平台)
- 运行环境要求
- 未检出明确要求
- 检测到的文件与系统行为
-
- 只读
- 允许写入 / 修改
- 网络行为
- 允许外网请求
- 安装命令数
- 无(仅作为资料)
需要注意: 未声明工具权限范围;实际权限由运行环境决定。
# Claude Skills Troubleshooting
## 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.
## 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 using `known_marketplaces.json` `lastUpdated`
- Missing, malformed, timezone-free, or future `lastUpdated` metadata
- Invalid plugin configurations
Treat `lastUpdated` as the only cache-freshness source. Do not fall back to
cache-directory modification times: marketplace updates can refresh nested
files without changing that directory timestamp. The diagnostic exits nonzero
for stale caches or invalid freshness metadata.
## Common Issues
### Issue 1: Plugin Installed But Not Showing in Available Skills
**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](https://github.com/anthropics/claude-code/issues/17832)) - plugins are added to `installed_plugins.json` but NOT automatically added to `enabledPlugins` in `settings.json`.
**Diagnosis:**
```bash
# 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"
```
**Solution:**
```bash
# 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
```
### Issue 2: Understanding Plugin State Architecture
**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:**
1. Exists in `installed_plugins.json` (registered)
2. Listed in `settings.json` → `enabledPlugins` with value `true`
### Issue 3: Marketplace Cache Stale
**Symptoms:**
- GitHub has latest changes
- Install finds plugin but gets old version
- Newly added plugins not visible
**Solution:**
```bash
# 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
```
### Issue 4: Plugin Not Found in Marketplace
**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
```
## 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'` |
## Batch Enable Missing Plugins
To enable all installed but disabled plugins from a marketplace:
```bash
python3 scripts/enable_all_plugins.py marketplace-name
```
## Skills vs Commands Architecture
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.
## References
- See `references/known_issues.md` for GitHub issue tracking
- See `references/architecture.md` for detailed plugin architecture
章节与文件索引
按说明文件中的顺序排列。
概述
快速诊断
问题 1:已安装插件但未显示可用技能
问题 2:了解插件状态架构
问题 3:市场缓存过时
文件/命令 -> known_marketplaces.json · lastUpdated · /plugin · installed_plugins.json · enabledPlugins · settings.json · ~/.claude/plugins/installed_plugins.json · ~/.claude/settings.json
内容校验值 -> 8ce25574fb3b
当前原文的自动摘译,尚未人工审校。
概述
诊断并解决常见的 Claude Code 插件和技能配置问题。此技能为插件安装、启用和激活问题提供系统的调试工作流程。
快速诊断
运行诊断脚本来识别常见问题: 该脚本检查: 安装的插件与启用的插件不匹配 settings.json 中缺少启用的插件条目 使用
known_marketplaces.jsonlastUpdated的过时市场缓存问题 1:已安装插件但未显示可用技能
症状:
/plugin显示插件已安装 技能未出现在技能工具的可用列表中 插件元数据存在于installed_plugins.json根本原因:已知错误 (GitHub #17832) - 插件被添加到installed_plugins.json,但不会自动添加到settings.json中的enabledPlugins。问题 2:了解插件状态架构
关键文件:文件·用途
~/.claude/plugins/installed_plugins.json·所有插件的注册表(已安装+禁用)~/.claude/settings.json→enabledPlugins·控制哪些插件处于活动状态~/.claude/plugins/known_marketplaces.json·注册的市场来源问题 3:市场缓存过时
症状:GitHub有最新更改安装找到插件但获取旧版本新添加的插件不可见解决方案: