Skill-Guide 🗂️

Локальный справочник всех скиллов и /-команд твоего Claude Code и Codex.
Разложены по категориям, на простом русском, с бейджами платформы, GitHub-источниками
и фасетной фильтрацией. Обновляется сам. Светлая и тёмная темы.

Что это

Если у тебя стоит Claude Code и/или Codex, у тебя десятки установленных
скиллов и /-команд, и в них легко потеряться. Skill-Guide сканирует их у тебя на
машине и собирает единую страницу: категории, поиск, «когда/как применять», платформа
(Claude/Codex/оба), GitHub-источник, доступные обновления и счётчик реальных вызовов.

Установка

Нужно: Python 3.8+ и установленный Claude Code и/или Codex (гид каталогизирует
их скиллы — без них каталог будет пустым).

git clone https://github.com/mcdenil-skills/skill-guide.git
cd skill-guide
./update.sh                      # сканирует твои скиллы → data/skills-data.js
open index.html                  # macOS; или открой файл в браузере вручную

Работает офлайн, без сервера. data/skills-data.js генерируется локально под твою
машину и в git не хранится.

С кнопкой «Обновить всё» (живой режим) — открой через локальный сервер:

./serve.sh                       # http://127.0.0.1:8777

Как это обновляется

Каталог собирается автоматически скриптом scripts/generate.py,
который сканирует три папки скиллов + кэш плагинов, определяет платформу и источник
и склеивает с курируемыми русскими описаниями.

Что показывает каждая карточка

• Описание — на русском, что делает скилл.
• КОГДА — в какой ситуации звать (триггерные фразы под твои задачи).
• КАК — как применить: для /-команд «Набери /имя», для остальных «просто опиши задачу».
• Платформа — Claude / Codex / оба (по расположению скилла).
• Источник — кликабельный GitHub-диплинк прямо в папку скилла, с ✓ если ссылка проверена (реальным запросом). Проверка — data/links.json.
• ↳ N× — сколько раз ты явно вызывал скилл (по логам сессий). Считает scripts/usage-scan.py.
• 🔄 v→v — доступно обновление. Кликни по бейджу — всплывёт инструкция, куда зайти и что нажать (gstack → кнопка/git pull; плагины → /plugin → Update). Считает scripts/check-updates.py.

Обновления скиллов

Гид показывает, что устарело; применение — по твоей команде (меняет файлы в системных папках, ничего молча):

./update-skills.sh          # показать, что можно обновить (только чтение, git fetch)
./update-skills.sh --apply  # применить git-обновления (gstack + витрины) и пересобрать

• gstack обновляется через git pull (или скилл gstack-upgrade).
• Плагины (superpowers и др.) — штатной командой /plugin update <имя> в Claude.
• Проверка версий (check-updates.py) ходит в сеть (git fetch), поэтому не в хуке — запускай сам или через ./update-skills.sh. Можно просто попросить меня «обнови такой-то скилл».

Кнопка «Обновить всё» прямо в гиде («живой режим»)

Статичная страница (file:// или онлайн-артефакт) НЕ может запускать команды на компьютере —
это запрет браузера. Чтобы кнопка в гиде реально работала, открой его через локальный сервер:

./serve.sh

Откроется http://127.0.0.1:8777/index.html, и в баннере появится рабочая кнопка «Обновить всё»:
нажатие делает git pull gstack + витрин и пересобирает каталог, страница сама обновляется.
Сервер слушает только localhost (снаружи недоступен). Обычный index.html без сервера
работает как раньше — только показывает статус, без кнопки.

Почему не launchd? macOS (TCC) не даёт фоновым процессам launchd читать файлы
в ~/Documents. Файлы launchd/ и scripts/install-autoupdate.sh оставлены как
опция — заработают, только если выдать «Full Disk Access» в Системных настройках.
Хук в контексте терминала таких ограничений не имеет и надёжнее.

Как добавить/причесать скилл

Автосканер сам находит новые скиллы. Если у скилла ещё нет русского описания,
он попадает в категорию «🆕 Не разобранные» с сырым текстом из frontmatter.

Чтобы причесать — добавь запись в data/overrides.json:

"имя-скилла": {
  "cat": "personal",
  "core": 1,
  "cmd": 1,
  "desc": "Что делает простым языком.",
  "when": "«когда звать», «триггерные фразы»"
}

Поля: cat — категория (id из блока categories), core — «твоё частое» (1/0),
cmd — это /-команда (1/0), desc — описание, when — когда звать.
Платформа и GitHub-источник подставляются генератором сами; переопределить можно
полями platform / source / sourceUrl.

Потом ./update.sh — и гид обновлён.

Как определяется платформа и источник

Платформа — по тому, где лежит скилл:

• ~/.agents/skills/ → оба (Claude + Codex, общий стор)
• только ~/.claude/skills/ или плагин → Claude
• ~/.codex/skills/ → Codex

Источник (GitHub) — из метаданных плагинов (known_marketplaces.json) и маркеров:
gstack → garrytan/gstack, superpowers → obra/superpowers,
плагины Anthropic → anthropics/claude-plugins-official, codex → openai/codex-plugin-cc.
Нераспознанные локальные — помечены «локальное».

Структура

Skill-Guide/
├── index.html                    ← сам гид (открываешь в браузере)
├── update.sh                     ← пересборка каталога (счётчики + генератор)
├── update-skills.sh              ← показать/применить обновления скиллов
├── serve.sh / serve.py           ← «живой режим»: гид на localhost с кнопкой «Обновить всё»
├── data/
│   ├── skills-data.js            ← авто-каталог (не править руками)
│   ├── overrides.json            ← курируемые русские описания + категории
│   ├── links.json                ← результат проверки GitHub-ссылок
│   ├── updates.json              ← статус обновлений (от check-updates.py)
│   └── usage.json                ← счётчики вызовов (от usage-scan.py)
├── scripts/
│   ├── generate.py               ← сканер каталога (ядро)
│   ├── usage-scan.py             ← счётчики вызовов из логов сессий
│   ├── check-updates.py          ← сравнение версий (git fetch, сеть)
│   ├── build-fonts.py            ← вшивает woff2 в assets/fonts.css
│   ├── build-standalone.py       ← self-contained версия для публикации
│   ├── install-autoupdate.sh     ← (опция) launchd, нужен Full Disk Access
│   └── uninstall-autoupdate.sh
├── assets/fonts/ + fonts.css     ← JetBrains Mono + IBM Plex Sans (офлайн)
├── launchd/skillguide.plist.tmpl  ← шаблон, install-скрипт подставит пути
└── dist/                         ← собранные standalone-файлы (в .gitignore)

Фильтрация

Поиск по имени + описанию + «когда звать». Слева фасеты (мультивыбор внутри группы = ИЛИ,
между группами = И): Статус (есть обновление / ни разу не звал) · Платформа · Категория ·
Источник. Быстрые тумблеры «Только частое» и «Только /команды». Сортировка: по категориям /
по вызовам / сначала частое / А–Я. Состояние фильтра сохраняется в URL — закреплённая
вкладка помнит вид. Горячие клавиши: / — фокус, Esc — сброс.

Как помочь (Contributing)

Самое ценное — русские описания скиллов: «что делает», «когда» и «как применять».
Автосканер находит скиллы сам, но красивый текст пишут люди. Добавить/поправить легко —
всё живёт в одном файле data/overrides.json, код трогать не нужно.
Полный гайд — в CONTRIBUTING.md.

Как добавить описание:

1. Форкни репозиторий и открой data/overrides.json.

2. В объект "skills" добавь (или поправь) запись по имени скилла:

   "имя-скилла": {
     "cat": "dev",
     "core": 0,
     "cmd": 1,
     "desc": "Что делает — простым языком, одно-два предложения.",
     "when": "«триггерные фразы», в какой ситуации звать",
     "how": "необязательно — по умолчанию подставится сам"
   }
   

   Поля: cat — id категории из блока "categories" того же файла (или новая категория);
   core — часто используемый (1/0); cmd — это /-команда (1/0); desc — описание;
   when — когда звать; how — необязательно. Платформу и GitHub-ссылку генератор
   подставляет сам.

3. Проверь локально: python3 scripts/validate.py (это же гоняет CI).

4. Открой Pull Request. CI проверит синтаксис, структуру данных и что в PR не попали
   личные/генерируемые файлы.

Другие вклады тоже приветствуются: новые категории, исправления ссылок в
data/links.json, улучшения гида (index.html) или скриптов. Стиль описаний —
простой человеческий русский, без канцелярита; ориентир — уже готовые записи в файле.

Лицензия

MIT.