API каталога, MCP-сервер и CLI

Коротко

• npx skillfoxx: установщик, который ставит запись каталога в ваших агентов и ведет lock-файл.
• MCP-сервер https://skillfoxx.ru/api/mcp: поиск, карточка записи, план установки под агента, подбор под проект, как в «Подбор с Foxx AI».
• REST API /api/v1: список записей, поиск, рецепты установки, подбор под проект и проверка файлов.
• Рецепты установки, подписанные ключом Ed25519, и их JSON-схема.
• Выгрузка /catalog.json по лицензии CC BY 4.0.
• Файлы для агентов: /llms.txt, /server.json, /.well-known/mcp.json.

Все ответы в JSON UTF-8. Разделы каталога в адресах и параметрах: skills, mcp, cli, plugins, workflows, prompts.

CLI: npx skillfoxx

Установщик ставит записи каталога в агентов на вашей машине. Пакет skillfoxx лежит в npm и распространяется по лицензии MIT, нужен Node.js 18.18 или новее.

npx skillfoxx add mcp/vv-mcp-server

npx skillfoxx search postgres
npx skillfoxx list
npx skillfoxx doctor
npx skillfoxx update
npx skillfoxx remove mcp/vv-mcp-server

Исходный код, сборка и сеть

• Исходный код CLI открыт: https://github.com/SkillFoxx-CLI/cli, лицензия MIT. Бандл в npm собран без минификации, его можно прочитать перед запуском.
• Пакет в npm собирает GitHub Actions из этого репозитория и подписывает происхождение сборки (provenance, SLSA): на странице пакета видно, из какого коммита он получен. Каждую версию владелец подтверждает двухфакторной защитой.
• CLI обращается только к skillfoxx.ru (подписанный рецепт записи и счетчик установок), api.github.com и raw.githubusercontent.com (файлы скилла на зафиксированном коммите).
• Счетчик установок анонимный: запись, агент, событие, версия CLI, случайный идентификатор и признак CI. Путей, переменных окружения и имени пользователя в нем нет. Отключить: DO_NOT_TRACK=1.

• Исходный код на GitHub
• Пакет skillfoxx в npm

Команды

Параметры

Куда CLI пишет

CLI кладет файлы скилла в .agents/skills/<имя> (для пользователя в ~/.agents/skills) и подключает к папке каждого агента символической ссылкой. Если ссылку создать нельзя, копирует папку. Там, где в таблице стоит «нет», CLI печатает инструкцию вместо правки.

Что CLI проверяет до установки

• Подпись рецепта ключами, вшитыми в CLI. Рецепт без подписи, с неизвестным ключом, для другой записи или выданный больше 24 часов назад CLI отвергает.
• CLI скачивает файлы скилла с GitHub на зафиксированном коммите и сверяет sha каждого файла и общий отпечаток.
• Запись снята с публикации или у нее открыт инцидент: установки нет, код 3. Рецепта нет или статус unsupported: код 4.
• Широкий доступ требует согласия: вопрос в терминале или флаг --yes. Без терминала и без --yes CLI завершается с кодом 5.
• Рецепты со статусами ai и review CLI ставит с предупреждением.
• Если нет node, python3, uvx или docker, CLI предупредит, что сервер без них не запустится, и продолжит.

Конфиги, секреты и резервные копии

• CLI правит конфиг по одному ключу: комментарии, отступы и чужие серверы остаются на месте.
• Перед правкой CLI сохраняет копию в ~/.skillfoxx/backups и держит 20 последних копий. Ошибка или Ctrl+C откатывает установку.
• В файл проекта секрет не попадает. CLI пишет ссылку на переменную окружения, если агент ее понимает (Claude Code, Gemini CLI, Cursor, VS Code, Zoo Code, OpenCode), иначе печатает инструкцию.
• Для пользователя CLI записывает значение секрета в конфиг агента с правами 600, как это делают сами агенты. В lock-файле значений секретов нет.
• Установщик сам не ставит плагины Claude Code: он печатает команды /plugin для чата. CLI-инструменты ставит через npm, pip, brew, cargo или go после вашего подтверждения.

Lock-файлы и язык

skillfoxx-lock.json в корне проекта (его стоит коммитить) и ~/.skillfoxx/lock.json для пользователя хранят запись, хеш рецепта, коммит, статус, уровень доступа, агентов, пути и даты. Другую папку вместо ~/.skillfoxx задает переменная SKILLFOXX_HOME.

CLI берет язык вывода из LC_ALL, LC_MESSAGES или LANG, затем из языка системы (на macOS из AppleLanguages). Если определить не получилось, пишет по-русски. Флаг --lang задает язык явно.

Коды выхода

Телеметрия

После add, update и remove CLI отправляет на адрес POST /api/v1/installs запись, агент, событие, версию CLI, признак CI и случайный идентификатор установки из ~/.skillfoxx/config.json. Пути, переменные и имя пользователя не уходят. Отключить: DO_NOT_TRACK=1, DISABLE_TELEMETRY=1 или SKILLFOXX_TELEMETRY=0.

Из этих событий складывается счетчик установок на карточке: разные устройства за 30 дней, только события add, без запусков в CI. Число появляется от 10 установок. События старше 90 дней сервер удаляет.

MCP-сервер

Адрес https://skillfoxx.ru/api/mcp, транспорт streamable HTTP без сессий, ответы в JSON. Ключ не нужен, лимит 120 запросов в минуту с одного IP-адреса.

Пишет в базу только report_install: он добавляет анонимное событие в счетчик установок. Остальные инструменты только читают каталог.

claude mcp add --transport http skillfoxx https://skillfoxx.ru/api/mcp

{
  "mcpServers": {
    "skillfoxx": {
      "url": "https://skillfoxx.ru/api/mcp"
    }
  }
}

{
  "servers": {
    "skillfoxx": {
      "type": "http",
      "url": "https://skillfoxx.ru/api/mcp"
    }
  }
}

[mcp_servers.skillfoxx]
url = "https://skillfoxx.ru/api/mcp"

Инструменты

lang принимает ru или en, по умолчанию ru. section: skills, mcp, cli, plugins, workflows, prompts. agent в plan_install: claude-code, cursor, vscode, codex, gemini-cli, devin, cline, zoo-code, opencode, zed, sourcecraft, coddy, antigravity, kiro; подходят и написания vs-code, github-copilot, windsurf, roo-code, gemini. Если у записи нет рецепта под этого агента, придет agent_not_supported со списком поддерживаемых агентов. Если рецепта нет совсем, plan равен null, а message объясняет почему.

Как сообщить об установке

• Агент вызывает plan_install, спрашивает пользователя, ставит запись и только после успешной установки вызывает report_install с reportToken.
• Токен действует 2 часа и привязан к записи и IP-адресу. С одного адреса в сутки засчитывается одна MCP-установка записи.
• Если ставили через npx skillfoxx, report_install не нужен: CLI сообщает сам. Если пользователь отказался от статистики, инструмент не вызывают.

В recommend_for_project отправляйте только выжимку о проекте, без кода и секретов. Сервер передает этот текст в OpenAI для подбора по смыслу и не сохраняет его.

REST API

Базовый адрес https://skillfoxx.ru/api/v1. Ключ не нужен. Лимиты считаются по IP-адресу за минуту, при превышении придет ответ 429.

GET /api/v1/entries

Опубликованные записи по 50 на страницу. Порядок как в каталоге: сначала выбор редакции, затем ★ репозитория, затем дата публикации.

Ответ: page, totalPages, totalDocs и entries с полями id, type, slug, title, titleOriginal, tagline, url, source, riskLevel, isRuStack, stars (★ репозитория), license, install (method и command). Кэш 5 минут, CORS открыт.

curl 'https://skillfoxx.ru/api/v1/entries?lang=ru&section=mcp&ru=1&page=1'

GET /api/v1/search

Поиск по опубликованным записям. q от 2 до 120 символов, lang, limit до 50 (по умолчанию 12). Ответ {"hits": [...]} с полями id, title, titleOriginal, tagline, type, href. href относительный и без префикса языка. Когда совпадений по словам мало, поиск добирает записи по смыслу через эмбеддинги OpenAI. Кэш на 1 минуту. Заголовка CORS у этого адреса нет: с вашего сайта в браузере вызывайте его через ваш сервер.

curl 'https://skillfoxx.ru/api/v1/search?q=postgres&lang=ru&limit=5'

GET /api/v1/recipe/<slug>

Находит разделы, в которых есть такой slug: {"matches": [{"section", "slug", "title"}]}. Этим адресом пользуется npx skillfoxx add <slug>. Сам рецепт отдает адрес с разделом, он описан ниже.

curl https://skillfoxx.ru/api/v1/recipe/vv-mcp-server

POST /api/v1/scan

Подбор под проект, как на странице «Подбор с Foxx AI» (/scan). Тело {"input": "...", "lang": "ru"}, input от 3 до 50 000 символов: описание задачи или package.json. Ответ: answer (текст модели), sources (записи с href и тем, что совпало) и mode (project или question). Текст запроса уходит в OpenAI. Лимит 20 запросов в минуту. Ответ 429 с телом {"error": "quota"} значит, что запросы на сегодня закончились; при "needLogin": true продолжить можно после входа через Яндекс ID.

curl -X POST https://skillfoxx.ru/api/v1/scan \
  -H 'content-type: application/json' \
  -d '{"input": "интернет-магазин на Next.js с оплатой ЮKassa", "lang": "ru"}'

POST /api/v1/validate

Проверка файла, как на странице /validator. Тело {"content": "...", "format": "skill_md"}. format: skill_md, plugin_json, server_json, agents_md или cursor_mdc; без него сервер определит формат сам. content до 200 000 символов. Лимит 60 запросов в минуту.

POST /api/v1/installs

Служебный адрес для событий CLI. Сервер принимает только запросы с User-Agent skillfoxx-cli/<версия>, остальным отвечает 202 и ничего не записывает. Чтобы ваша интеграция попадала в счетчик, вызывайте report_install в MCP.

Рецепты установки и подпись

Рецепт описывает, что ставится (скилл, MCP-сервер, плагин, CLI или правила), из какого коммита и какие переменные нужны. Как мы собираем и сверяем рецепты, написано в методологии.

curl -i https://skillfoxx.ru/api/v1/recipe/mcp/vv-mcp-server

Ответ: entry (slug, type, section, url, canonicalSource), recipe (объект по схеме или null), status, reason (только у unsupported и review), risk (level и reasons), officialVendor, checkedAt, hash, blocked (открытый инцидент серьезности high или critical, иначе null) и issuedAt. Адрес и причины берутся из русской карточки. Кэш 5 минут, ETag и ответ 304 на If-None-Match, лимит 60 запросов в минуту, 404 для записи, которой нет в каталоге.

• JSON-схема рецепта

Статусы

Подпись Ed25519

Каждый ответ рецепта подписан. Заголовок x-skillfoxx-signature имеет вид v1;kid=<ключ>;sig=<подпись в base64url>. Подписано сообщение из строки skillfoxx-recipe-v1, перевода строки и тела ответа байт в байт.

Открытые ключи (SPKI DER в base64) лежат в /.well-known/skillfoxx-recipe-keys.json, тот же список вшит в CLI. По плану ротации новый ключ появляется в списке за 30 дней до переключения сервера, старый исчезает через 30 дней после.

// verify.mjs, Node.js 18+: node verify.mjs
import { createPublicKey, verify } from 'node:crypto'

const base = 'https://skillfoxx.ru'
const { keys } = await (await fetch(`${base}/.well-known/skillfoxx-recipe-keys.json`)).json()
const res = await fetch(`${base}/api/v1/recipe/mcp/vv-mcp-server`)
const body = await res.text()
const [, kid, sig] = /^v1;kid=(sf-[0-9a-f]{8});sig=([A-Za-z0-9_-]+)$/.exec(res.headers.get('x-skillfoxx-signature'))
const key = createPublicKey({ key: Buffer.from(keys.find((k) => k.kid === kid).publicKey, 'base64'), format: 'der', type: 'spki' })
console.log(kid, verify(null, Buffer.from('skillfoxx-recipe-v1\n' + body), key, Buffer.from(sig, 'base64url')))

Проверяйте подпись до разбора JSON и сверяйте entry.section и entry.slug с тем, что запрашивали. CLI вдобавок отвергает ответ, если issuedAt старше 24 часов.

• Открытые ключи подписи

Выгрузка каталога

Все опубликованные записи одним файлом: /catalog.json с русскими текстами и /catalog.en.json с английскими (где перевода нет, текст русский). Сервер собирает файл по запросу и держит в памяти до часа.

Верхний уровень: version, generatedAt, lang, license (name, url, attribution, scope), count и entries. Поля записи: slug, section, type, title, titleOriginal, tagline, url, canonicalSource, source, risk, officialVendor, recipe, recipeStatus, recipeCheckedAt, recipeHash, updatedAt.

Кэш на час, ETag и ответ 304 на If-None-Match, заголовок Link с rel="license". Лимит 20 запросов в минуту. Если база недоступна, сервер отдает прошлую версию, а если ее нет, отвечает 503 с Retry-After.

curl -O https://skillfoxx.ru/catalog.json

curl -s https://skillfoxx.ru/catalog.json | jq -r '.entries[] | select(.recipeStatus == "auto") | .url'

• /catalog.json
• /catalog.en.json

llms.txt и файлы для агентов

• /llms.txt
• /server.json
• /.well-known/mcp.json
• /rss.xml

Лимиты и кэш

Поминутные счетчики сервер держит в памяти. Полную копию каталога берите из catalog.json: один файл скачивается быстрее обхода страниц и не нагружает сайт.

Лицензии

• Тексты и метаданные SkillFoxx в API, MCP и выгрузке доступны по лицензии CC BY 4.0. Указывайте источник «SkillFoxx (skillfoxx.ru)» со ссылкой на сайт.
• Код записей принадлежит их авторам и распространяется по их лицензиям. В ответы и выгрузку он не входит, там только ссылки на первоисточник.
• CLI skillfoxx распространяется по лицензии MIT, а лицензии вшитых библиотек лежат в THIRD_PARTY_LICENSES.txt внутри пакета.
• Звезды и лицензии записей приходят из GitHub и относятся ко всему репозиторию.

Связь

Об ошибке в записи или рецепте сообщите кнопкой «Сообщить о проблеме» на странице записи. Свой скилл или сервер предложите через форму добавления. Новости API и CLI выходят в Telegram-канале @skillfoxxru.

• Предложить запись
• Как мы отбираем и проверяем записи
• Условия использования
• Политика конфиденциальности