claude-skills-troubleshooting — скилл для Claude Code
Скилл claude-skills-troubleshooting диагностирует, почему плагин или скилл не активируется в Claude Code. Помогает проверить регистрацию, настройки и кэш маркетплейса.
MIT 990 установок ★ 1 540 обновлён 2026-10-25
npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a claude-codeЧто делает claude-skills-troubleshooting
Скилл разбирает случаи, когда установленный плагин не появляется среди доступных скиллов, не запускается или пропущен в enabledPlugins файла settings.json. Он сопоставляет записи в installed_plugins.json и settings.json, проверяет зарегистрированные маркетплейсы и состояние кэша.
В комплекте есть scripts/diagnose_plugins.py для диагностики и scripts/enable_all_plugins.py для включения всех установленных, но отключённых плагинов маркетплейса. Также описаны команды для обновления кэша, проверки marketplace.json, поиска файла SKILL.md и анализа symlink-сценария. Плагин активен только при наличии регистрации в installed_plugins.json и значения true в enabledPlugins, поэтому одной установки бывает недостаточно.
Скилл рассчитан на Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI и OpenCode. Для диагностики нужен доступ к конфигурационным файлам Claude Code и Python 3 для запуска скриптов.
Какие задачи решает
- найти установленный, но отключённый плагин
- проверить записи в
installed_plugins.jsonиsettings.json - обновить устаревший кэш маркетплейса
- проверить конфигурацию
marketplace.json - включить все плагины маркетплейса скриптом
Примеры запросов агенту
- Проверь, почему установленный плагин не появляется среди доступных скиллов.
- Запусти
python3 scripts/diagnose_plugins.pyи разберись с найденными проблемами. - Проверь, почему
enabledPluginsне совпадает сinstalled_plugins.json.
Как установить claude-skills-troubleshooting
1Через Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a claude-code2Вручную: положить файлы
~/.claude/skills/claude-skills-troubleshooting/SKILL.mdПапка скилла целиком; для одного проекта — .claude/skills/claude-skills-troubleshooting/
1Через Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a codex2Вручную: положить файлы
.agents/skills/claude-skills-troubleshooting/SKILL.mdДля всех проектов — ~/.agents/skills/
1Через Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a cursor2Вручную: положить файлы
.cursor/skills/claude-skills-troubleshooting/SKILL.mdCursor читает и .agents/skills/, и .claude/skills/
1GitHub CLI
gh skill install daymade/claude-code-skills daymade-claude-code/claude-skills-troubleshooting/SKILL.md2Вручную: положить файлы
.github/skills/claude-skills-troubleshooting/SKILL.md1Через Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a gemini-cli2Командой платформы
gemini skills install https://github.com/daymade/claude-code-skills --path daymade-claude-code/claude-skills-troubleshootingВручную: положить файлы
.devin/skills/claude-skills-troubleshooting/SKILL.mdСтарый путь .windsurf/skills/ тоже читается
Через Skills CLI (Vercel)
npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a opencodeClaude.ai
Упакуйте папку в zip и загрузите в Settings → Capabilities → Skills
По шагам, с командами для каждой платформы: Как установить скилл в Claude Code: пять способов
Вопросы о claude-skills-troubleshooting
Как установить claude-skills-troubleshooting в Claude Code?
Выполните npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a claude-code. Затем проверьте файл ~/.claude/skills/claude-skills-troubleshooting/SKILL.md.
Что делает claude-skills-troubleshooting?
Скилл ищет причины проблем с установкой, регистрацией и активацией плагинов Claude Code. Он проверяет настройки, метаданные кэша и соответствие записей об установленных и включённых плагинах.
Когда плагин считается активным в Claude Code?
Он должен быть зарегистрирован в installed_plugins.json и иметь значение true в разделе enabledPlugins файла settings.json. Одна запись об установке этого не гарантирует.
Исходный текст
SKILL.md · MIT
---
name: claude-skills-troubleshooting
disable-model-invocation: true
description: Diagnose and resolve Claude Code plugin and skill issues. This skill should be used when plugins are installed but not showing in available skills list, skills are not activating as expected, or when troubleshooting enabledPlugins configuration in settings.json. Triggers include "plugin not working", "skill not showing", "installed but disabled", or "enabledPlugins" issues.
---
# 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 in both directions (installed-but-not-enabled and enabled-but-not-registered)
- 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
```
**Mirror variant — enabled but not registered:** If diagnosis instead shows the plugin in `enabledPlugins` but NOT in `installed_plugins.json`, the cause is the symlink-skip bug: the install ran under a config dir where `installed_plugins.json` is a symlink (multi-profile shared setups), and the CLI silently skipped writing it. See `references/known_issues.md` → "Symlinked installed_plugins.json". Fix:
```bash
# 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
```
### 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
© daymade · MIT · daymade/claude-code-skills