skilljit

Своевременная маршрутизация навыков и MCP-инструментов для Claude — установите тысячи навыков по цене одного в токенах. Ничего не загружается в контекст, пока задача действительно в этом не нуждается.

Почему список инструментов никогда не меняется

Очевидный способ добавлять инструменты по требованию — уведомление MCP notifications/tools/list_changed. Оно сломано в Claude Desktop — anthropics/claude-code#50339 документирует, что оно игнорируется на протяжении 336+ версий (пустые возможности клиента, обработчик SDK, который никогда не срабатывает, замороженная ссылка на список инструментов), и Anthropic закрыл этот issue как не запланировано. Рекомендуемый обходной путь из самого issue — "объявить все инструменты при запуске и маршрутизировать внутренне через параметры режима/действия".

Именно это и делает skilljit. Его список MCP-инструментов фиксирован и никогда не меняется — небольшой, постоянный набор инструментов, всегда. Навыки и вышестоящие MCP-инструменты находятся и загружаются через эти инструменты, а не путём повторной регистрации списка инструментов. Поэтому skilljit работает на Claude Desktop, Claude Code, Codex и Cursor, в то время как прокси на основе list_changed незаметно деградируют по крайней мере на одном из них.

Related MCP server: MCPNexus

Проблема

Agent Skills от Claude используют прогрессивное раскрытие: каждый навык name + description (~100 токенов) находится в системном промпте на каждом ходу, и только тело загружается по требованию. Это работает при 10 навыках. Это рушится в масштабе — экосистема уже существует, с десятками тысяч навыков в тысячах репозиториев. Установка 200 из них стоит десятки тысяч токенов за ход, навсегда. Поэтому никто этого не делает — все устанавливают десять, а остальные недоступны.

У MCP та же проблема, но хуже: полные схемы инструментов каждого подключённого сервера загружаются при запуске, обычно 20–50 тыс. токенов до того, как пользователь что-либо введёт.

Установка

npx -y skilljit sync

Это основной путь — экосистема MCP в первую очередь ориентирована на npx, и конфиги Claude Code / Desktop уже ожидают такую форму.

Также опубликован тонкий Python-компаньон для пользователей claude-agent-sdk, которые хотят запрашивать тот же каталог напрямую, а не через MCP:

pip install skilljit

См. python/README.md о том, что этот пакет делает и чего не делает — он перенаправляет CLI на npx -y skilljit и добавляет read-only Catalog для Python.

Поддержка версий Node

skilljit, @skilljit/mcp и @skilljit/proxy требуют Node 18+ — этот минимум напрямую исходит из @modelcontextprotocol/sdk, от которого зависят MCP-сервер и прокси-слой и который сам требует 18+. Обойти это невозможно без отказа от поддержки MCP.

@skilljit/core (библиотека каталога/поиска, без зависимости от MCP) поддерживает Node 16+ для тех, кто использует его API Catalog/ingestGithubRepo напрямую. На Node 18+ это установка без компиляции (better-sqlite3 поставляет готовый бинарник). На Node 16/17 у better-sqlite3 нет готового бинарника для этого ABI ни на одной платформе, поэтому npm откатывается к компиляции из исходников через node-gyp — для этого нужен C++ тулчейн и Python с доступным модулем distutils (до 3.12). Это стандартное требование для нативных Node-модулей, а не специфический шаг skilljit, но это означает, что установка @skilljit/core на Node 16/17 не гарантирует такой же простоты, как на 18+.

Быстрый старт

# 1. Build the local catalog from GitHub sources (SQLite, ~/.skilljit/catalog.db)
skilljit sync

# 2. Search it — no network call, no context cost
skilljit search "postgres migration"

# 3. Point your MCP client at the server
skilljit serve

Добавьте в конфиг вашего MCP-клиента (например, claude_desktop_config.json):

{
  "mcpServers": {
    "skilljit": {
      "command": "npx",
      "args": ["-y", "skilljit", "serve"]
    }
  }
}

Другие команды: skilljit stats (размер каталога + как читать живую экономию), skilljit init <configPath> (предпросмотр маршрутизации ваших существующих MCP-серверов через skilljit — никогда не изменяет оригинал), skilljit adopt <configPath> (применить), skilljit doctor [configPath] (проверить, что вышестоящие серверы всё ещё работают), skilljit restore <configPath> (отменить adopt).

Добавление своих навыков в sync

По умолчанию sync берёт только из небольшого курируемого списка публичных репозиториев. Чтобы добавить свои:

# Another public (or your-token-authenticated private) GitHub repo:
skilljit sync --repo your-org/internal-skills --token "$SKILLJIT_GITHUB_TOKEN"

# Any git remote at all — self-hosted, GitLab, Bitbucket, or a private repo
# reached over SSH — using whatever git credentials are already set up on
# this machine. No GitHub API token needed for this path.
skilljit sync --git git@git.internal.example.com:team/skills.git

Оба флага повторяемы. Источники --git обрабатываются через голый зеркальный клон плюс git worktree, а не через GitHub API: первая синхронизация оплачивает полный клон, каждая последующая — это дешёвый git fetch + checkout worktree — без лимита скорости, без токена, работает с чем угодно, что доступно самому git.

Шесть инструментов

skilljit предоставляет фиксированную поверхность — она никогда не растёт и не сжимается во время выполнения.

skill_find → skill_load → skill_read_file — это прогрессивное раскрытие, перестроенное как вытягивание, до самого низа: постоянно загружаемая стоимость перестаёт масштабироваться с размером каталога, а вложенные справочные документы/скрипты навыка остаются вне контекста, пока не будут названы по пути, даже после загрузки самого навыка.

tool_find и tool_call появляются только после настройки вышестоящих MCP-серверов через skilljit adopt (см. ниже) — в режиме только навыков поверхность составляет 4 инструмента, а не 6. Именно это делает половину навыков независимо поставляемой и тестируемой от прокси-половины.

Несколько вкладок / параллельные сессии

Запуск нескольких вкладок Claude Code одновременно для разных задач — это именно тот случай, когда стоимость "каждая вкладка платит за каждый установленный навык" умножается: N открытых вкладок означают, что эти накладные расходы на ход оплачиваются N раз одновременно. skilljit уже снижает эту стоимость на вкладку до фиксированных нескольких инструментов независимо от размера каталога, но skilljit_stats() идёт дальше: базовые/фактические числа каждой сессии также записываются в общий catalog.db (тот же файл, на который уже указывает процесс skilljit serve каждой вкладки), поэтому сообщаемые итоги являются накопительными по всем вкладкам, которые у вас были открыты, а не только по той, из которой вы спрашиваете. Потеря вкладки не теряет это число — оно уже было надёжно записано, а не хранилось только в памяти этой вкладки.

Это не восстанавливает сам разговор потерянной вкладки — это функция сессии Claude Code (claude --resume / --continue), не связанная с skilljit. Что именно исправляется — это слепое пятно в учёте токенов: "сколько skilljit на самом деле сэкономил мне сегодня, учитывая всё, что у меня было открыто", переживая смерть любой одной вкладки.

MCP-прокси — маршрутизация ваших других MCP-серверов

Передача skilljit serve --config <path> (путь к конфигу, на котором вы ранее запускали skilljit adopt) включает tool_find/tool_call для принятых серверов. Безопасность здесь на первом месте, поскольку это касается конфигов, на которые вы уже полагаетесь:

• skilljit init <configPath> никогда не изменяет исходный файл — он записывает предлагаемый конфиг и выводит diff.

• skilljit adopt <configPath> по умолчанию является пробным запуском; передайте --yes, чтобы фактически записать изменение, после резервного копирования оригинала.

• --keep server1,server2 оставляет эти серверы нетронутыми — полностью видимыми в статическом списке инструментов, без обхода через tool_find. Полезно для инструментов на горячем пути, которые вы вызываете на каждом ходу. (Keep применяется к серверу, а не к инструменту, в этой версии.)

• skilljit doctor [configPath] проверяет, что каждый принятый вышестоящий сервер всё ещё запускается, выполняет рукопожатие и перечисляет инструменты.

• skilljit restore <configPath> — одна команда, возвращающая исходный конфиг.

• Недоступность одного вышестоящего MCP-сервера не влияет на другие: tool_call возвращает чистую ошибку для этого сервера, всё остальное продолжает работать.

Безопасность

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

• Каждый результат skill_find показывает статус аудита навыка рядом с его описанием.

• skill_load громко предупреждает в возвращаемом содержимом, когда навык не прошёл аудит или не был проверен вообще — та же позиция, что и при установке программного обеспечения из неизвестного источника.

Бенчмарк

bench/ поставляет размеченный набор из 41 пары (задача → правильный навык) и каркас для recall@k, так что "поиск работает" — это измеряемое утверждение, а не ощущение. Текущие цифры, воспроизводимые с помощью node bench/run.mjs:

skilljit bench — 41 queries over 41 skills

recall@1: 37/41  (90.2%)
recall@3: 38/41  (92.7%)
recall@8: 41/41  (100.0%)

Поиск — это SQLite FTS5 + BM25 — без эмбеддингов в v1. Это осознанное решение YAGNI: FTS5 поставляется одинаково в обеих реализациях — Node (better-sqlite3) и Python (stdlib), без загрузки моделей или дополнительных зависимостей времени выполнения. Остаточный риск recall (описания навыков семантичны — "используйте, когда пользователь упоминает PDF…") структурно смягчён: skill_find возвращает несколько кандидатов для рассмотрения и повторных запросов Claude, а не фиксируется на одноразовом top-1 результате. Эмбеддинги остаются опциональной опцией, которую добавят только если этот бенчмарк покажет, что recall FTS5 действительно недостаточен — три промаха выше (все почти попадания, правильный навык чуть за пределами top-3) являются конкретными кандидатами для этого решения.

Публикация

Пуш тега v* (например, v0.1.2) запускает CI, затем публикует каждый пакет в npm и PyPI через Trusted Publishing (OIDC) — без долгоживущих секретов NPM_TOKEN/PYPI_TOKEN в этом репозитории. См. .github/workflows/release.yml.

Требуется одноразовая настройка перед этим, выполняется вручную (не может быть автоматизирована):

• На npmjs.com зарегистрируйте Trusted Publisher для каждого из @skilljit/core, @skilljit/proxy, @skilljit/mcp и skilljit, указав этот репозиторий, файл workflow release.yml и окружение npm.

• На pypi.org зарегистрируйте Trusted Publisher для проекта skilljit, указав этот репозиторий, файл workflow release.yml и окружение pypi.

Архитектура

skilljit/
  packages/core/     catalog store, FTS5 index, ranking, token accounting
  packages/proxy/    upstream MCP server management, config adopt/restore, tool_find/tool_call routing
  packages/mcp/      the MCP stdio server (the fixed tool surface, see "The six tools" above)
  packages/cli/      skilljit sync | search | serve | stats | init | adopt | restore | doctor
  python/            pip package — CLI shim + read-only query API for Agent SDK users
  bench/             labeled task→skill eval set + recall@k harness

TypeScript — единственная реализация; пакет PyPI — это тонкая, честная обёртка вокруг него, а не вторая реализация логики ранжирования.

Лицензия

MIT