К основному содержанию
скилл CX Codex

claude-skills-troubleshooting — скилл для Claude Code

Скилл claude-skills-troubleshooting диагностирует, почему плагин или скилл не активируется в Claude Code. Помогает проверить регистрацию, настройки и кэш маркетплейса.

MIT 990 установок ★ 1 540 обновлён 2026-10-25

Установить в Claude Code · Через Skills CLI (Vercel) Все способы и платформы ↓
npx skills add daymade/claude-code-skills --skill claude-skills-troubleshooting -a claude-code
Открыть на GitHub

Что делает 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-code

2Вручную: положить файлы

~/.claude/skills/claude-skills-troubleshooting/SKILL.md

Папка скилла целиком; для одного проекта — .claude/skills/claude-skills-troubleshooting/

По шагам, с командами для каждой платформы: Как установить скилл в 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

Похожие скиллы

Все скиллы по теме «Настройка агента: память, контекст, субагенты» →
grepai-troubleshooting yoanbernabeu Скилл grepai-troubleshooting помогает найти причину сбоев GrepAI: пустой или устаревший индекс, плохие результаты поиска, ошибки подключения и конфигурации. CX Codex +1 727установок troubleshooting-astro-deployments astronomer Скилл troubleshooting-astro-deployments ведёт агента по шагам диагностики продакшн-развёртываний Astronomer через Astro CLI: логи, ошибки, переменные окружения. CX Codex +1 678установок troubleshooting-guide davila7 Команда troubleshooting-guide для Claude Code генерирует документацию по устранению неисправностей: процедуры диагностики, частые проблемы и решения. Запускается с компонентом или флагом, например --database. CX Codex +1 397установок troubleshooting-application-failures aws Скилл troubleshooting-application-failures для Claude Code анализирует CloudWatch, когда приложение падает и причину нужно искать в логах. CX Codex +1 7 300установок troubleshooting-efs aws Скилл troubleshooting-efs для Claude Code, Codex, Cursor, GitHub Copilot и Gemini CLI, который диагностирует и исправляет проблемы с Amazon EFS. CX Codex +1 6 700установок gke-workload-troubleshooting официальный google Скилл gke-workload-troubleshooting для Claude Code ищет причины сбоев GKE-нагрузок по логам и событиям. Разбирает незапускающиеся поды и повторные перезапуски. CX Codex +1 4 600установок

Из того же набора102

Весь набор →
llm-icon-finder Скилл llm-icon-finder для Claude Code, который находит иконки ИИ-моделей и провайдеров в библиотеке lobe-icons. Собирает CDN-ссылки на SVG, PNG и WEBP, а при запросе скачивает файлы через curl. CX Codex +1 1 000установок video-comparer Скилл video-comparer сравнивает два видео и собирает HTML-отчёт с метриками PSNR и SSIM, а также покадровым просмотром до и после сжатия. CX Codex +1 1 000установок github-contributor Скилл github-contributor для Claude Code помогает готовить pull request в чужой open-source проект: от проверки правил до ответа на замечания бота. Он включается по просьбе исправить код в upstream-репозитории или открыть PR. CX Codex +1 1 000установок teams-channel-post-writer Скилл teams-channel-post-writer пишет обучающие посты в канал Teams про Claude: разбор фич, советы, примеры промптов и принципы вроде context engineering. CX Codex +1 999установок repomix-safe-mixer Скилл repomix-safe-mixer сканирует проект на захардкоженные ключи и токены и не даёт repomix упаковать код, пока секреты не убраны. CX Codex +1 974установок financial-data-collector Скилл financial-data-collector собирает реальные финансовые данные по публичным компаниям США из yfinance и отдаёт структурированный JSON для DCF, сравнений и разбора отчётности. CX Codex +1 946установок doc-to-markdown Скилл doc-to-markdown для Claude Code и Codex конвертирует DOCX, PDF, PPTX и сохранённый HTML в Markdown с автоматической зачисткой разметки. Включается при запросах на парсинг документов. CX Codex +1 945установок repomix-unmixer Скилл repomix-unmixer для Claude Code и Codex, который распаковывает репозитории из файлов Repomix обратно в дерево каталогов. Работает с форматами XML, Markdown и JSON. CX Codex +1 945установок

Спонсоры проекта

Компании, которые помогают держать аналитику открытой