skill-compass: хук, который сам подсказывает Claude Code нужные скиллы / Хабр

У Claude Code есть одна неприятная особенность, про которую редко говорят вслух. Можно навесить на агента огромную библиотеку скиллов — дизайн, проектирование API, миграции БД, ревью безопасности, отдельные наборы под каждый язык, — и всё это будет честно лежать в ~/.claude/skills/. Нужный скилл почти всегда там есть. Проблема не в том, что его нет. Проблема в том, что про него надо вспомнить в нужный момент.

На практике это выглядит так: вы просите «поправь форму регистрации», модель бодро лезет писать код, а скилл по дизайну интерфейсов и скилл по ревью авторизации так и остаются непрочитанными. Не потому что агент плохой, а потому что библиотека большая, а внимание ограничено. Чем больше скиллов вы ставите, тем сильнее этот эффект: полезного арсенала всё больше, а попадание в него — всё реже.

skill-compass решает ровно эту задачу. Это маленький хук для Claude Code, который смотрит на проект перед агентом и подсказывает, какие скиллы подключить — до того, как написана первая строка кода. Без зависимостей, один файл на Node, около 200 строк, которые читаются за один присест.

Идея в одну строку

«Убрать необходимость вспоминать». На каждом промте хук осматривает то, что лежит перед агентом, и отдаёт короткий точный список подходящих скиллов. Дизайн-скилл срабатывает на UI-работе, security-скилл — на авторизации, миграционный — на изменении схемы. Автоматически и без участия человека.

Ключевое слово — точный. Если хуку нечего сказать (нет манифеста, нет ключевого слова, нет находки), он молчит, а не вываливает простыню «на всякий случай». Шум хуже тишины: к подсказкам, которые сыплются всегда и невпопад, агент быстро привыкает игнорировать.

Как это работает: три сигнала

Внутри всё устроено по принципу match → inject и укладывается в единицы миллисекунд. Хук читает три независимых сигнала.

1. Файлы проекта. Корень репозитория сканируется на один уровень вглубь: манифесты зависимостей, имена папок, расширения файлов. Это сопоставляется со стеками (Rust, Next.js, Django и так далее) и сквозными направлениями — UI, API, база, авторизация, LLM, инфраструктура. Увидел Cargo.toml — это Rust. Увидел prisma/ и *.sql — это работа с базой и миграциями.

2. Текст вашего промта. Хук ловит ключевые слова проекта и темы прямо в формулировке запроса. Это важный момент: он срабатывает, даже если вы запускаете агента из «junk-drawer» каталога — условного рабочего стола, забитого десятком проектов без общего манифеста в корне. Пишете «найди clickhouse-миграцию и почини» — и роутинг отрабатывает ещё до того, как открыт хоть один файл.

3. То, что агент находит по ходу дела. Отдельный хук на PostToolUse смотрит результаты Bash, Grep, Glob, Read, Task. Как только какой-то инструмент выдаёт известное ключевое слово — путь, имя зависимости, строку совпадения, — подходящие скиллы вбрасываются прямо рядом с этим результатом. Агент сам раскопал, что в проекте используется Redis? Скилл по Redis подключается в ту же секунду.

Найденные скиллы вставляются компактной заметкой. Один раз на набор-сигнал за сессию, повторно — только когда состав детекта поменялся. Никакого долбления одним и тем же текстом на каждый чих.

Забавный мета-момент: пока я готовил этот материал и грепал репозиторий по ключевым словам, хук сработал сам на результат моего же grep и предложил мне релевантные скиллы. То есть инструмент честно делает ровно то, что заявлено, — ловит находку инструмента на лету.

Азимуты, которые он читает

«Направления» (в терминах проекта — азимуты) — это сквозные слои поверх языковых стеков. Базовый набор:

Азимут	Триггеры	Какие скиллы подключает
UI	`react`, `vue`, `next`, `.tsx`, `components/`	`frontend-design`, `make-interfaces-feel-better`
API	`express`, `fastapi`, `app/api/`, `routes/`	`api-design`, `backend-patterns`
БД	`prisma`, `drizzle`, `sqlalchemy`, `*.sql`	`database-migrations`, `postgres-patterns`
AUTH	`next-auth`, `stripe`, `jwt`, `auth/`	`security-review`
LLM	`anthropic`, `openai`, `langchain`	`claude-api`, `agent-harness-construction`
INFRA	`Dockerfile`, `compose.yml`, `k8s/`	`docker-patterns`, `deployment-patterns`

Плюс к этому — 16 языковых стеков (Rust, Go, Python, TypeScript, Next.js, React, Vue, Java, Spring Boot, Kotlin, Swift, Dart/Flutter, PHP/Laravel, C#, C/C++) и отдельный блок keywords, который маршрутизирует по имени проекта или темы прямо из промта либо находки инструмента: SEO, accessibility, deep research, видео, Claude API, homelab и так далее. Каждая строка живёт в directions.json и правится руками.

Настройка: один объект в JSON

Вся логика роутинга вынесена в directions.json. Новый стек или направление добавляется одним объектом — код трогать не нужно, хук читает таблицу на лету.

{
  "id": "mobile",
  "name": "Mobile",
  "deps": ["react-native", "expo"],   // ищется в манифестах зависимостей
  "paths": ["ios", "android"],         // имена папок/файлов в корне
  "ext": [".kt", ".swift"],            // присутствующие расширения
  "skills": ["ecc:react-native-patterns"]
}

Срабатывает любое совпадение из deps / paths / ext. Поле skills — это просто строки: наводите азимут на любое имя установленного у вас скилла. Хотите свой набор под внутренний фреймворк команды — добавили запись, прогнали self-test, готово.

Кстати про self-test. В compass.js зашит набор фикстур-проектов и проверок:

node compass.js --self-test

Он гоняет детекцию стеков, роутинг направлений и «guard на пустой проект», после чего печатает ALL PASSED (или падает с ненулевым кодом). Правило простое: меняешь directions.json — прогоняешь self-test. Если хук вдруг начал советовать ерунду, сначала воспроизводишь баг новым кейсом здесь, а уже потом лезешь в движок.

Установка

Нужны Node.js и собственно Claude Code.

git clone https://github.com/by-sonic/skill-compass
node skill-compass/install.js

Установщик копирует два файла в ~/.claude/skill-compass/ и регистрирует два хука — UserPromptSubmit (промт + проект) и PostToolUse (находки инструментов по ходу работы). После этого нужно перезапустить Claude Code: хуки подхватываются при старте процесса. Повторный запуск установщика идемпотентен — это безопасный no-op.

Если ставить руками не хочется, проект ещё и оформлен как Agent Skill — тогда Claude сам поставит и обслужит хук по просьбе. Достаточно указать ему на каталог skill/skill-compass/ и сказать что-то вроде «поставь skill-compass» или «добавь азимут mobile».

Выключить без удаления можно переменной окружения:

SKILL_COMPASS=off       # тихо отключить на сессию
node install.js --uninstall   # снять хук, файлы остаются на месте

Что он куда-нибудь отправляет

Ничего. Хук работает локально, читает файлы вашего проекта и пишет заметку в ваш же промт. Ноль сетевых обращений, ноль телеметрии, ноль зависимостей. Это намеренное проектное решение: инструмент, который лезет читать ваш код, должен быть достаточно маленьким, чтобы вы могли прочитать его сами и убедиться, что он не делает ничего лишнего. Двести строк Node — это как раз тот размер, который реально вычитать глазами.

Кому это нужно

Если у вас в Claude Code стоит десяток-другой скиллов и вы периодически ловите себя на мысли «блин, был же скилл ровно под это» — skill-compass закрывает именно этот разрыв. Чем больше библиотека, тем заметнее польза. На пустом наборе скиллов хук вам ничего не даст: подсказывать нечего.

Самые полезные контрибьюции в проект — новые стеки и направления. Добавляете протестированную запись в directions.json плюс соответствующий кейс в фикстуры self-test, без новых зависимостей — и шлёте PR.

Репозиторий проекта на Гитхабе. Лицензия MIT.