skill-retrieval-mcp

Семантический поиск по проверенной на лицензии коллекции из 374 навыков агентов, предоставляемый вашему кодирующему агенту через MCP. Работает локально, отвечает за однозначные миллисекунды, не совершает ни одного вызова API.

Совместим с Claude Code, Codex CLI, Gemini CLI, Cursor, OpenClaw, Hermes и любым MCP-совместимым агентом.

You: "Deploy this service to GKE"

─── Step 1: the agent searches ───────────────────────────────────────

Agent: search_skills("deploy a containerised service on kubernetes")   ← 6ms
     → 5 results (summaries only, no full instructions):
       1. "gke-service-networking"   (0.56) - Gateway API, Ingress, Cloud Armor, NEGs, managed SSL
       2. "gke-workload-scaling"     (0.51) - HPA and VPA for GKE workloads
       3. "gke-manifest-generation"  (0.51) - Production-ready Kubernetes YAML for Autopilot/Standard
       4. "gke-app-onboarding"       (0.46) - Containerizing and deploying an app to GKE for the first time
       5. "gke-basics"               (0.44) - Cluster provisioning, credentials, Autopilot vs Standard

─── Step 2: it reads the descriptions and picks #4, not #1 ───────────

Agent: get_skill("gke-app-onboarding")
     → gets the full guide: containerization, manifests, migration path
     → writes the Dockerfile and deployment.yaml

─── Step 3: a new need emerges mid-task ──────────────────────────────

Agent: # the service has to survive traffic spikes — search again
       search_skills("autoscale pods on cpu and memory")               ← 6ms
     → "gke-workload-scaling" (0.61) - Horizontal and Vertical Pod Autoscaler for GKE
     → reads the guide, adds the HPA manifest

Оба поиска — реальный результат работы поставляемой коллекции, а не иллюстрация. Три вещи в ней составляют всю суть дизайна:

• Поиск возвращает сводки, а не инструкции. Пять сводок стоят несколько сотен токенов; единственный навык, который агент действительно читает, стоит около 2400.

• Лучший результат не всегда правильный. Агент выбрал #4, потому что его описание говорит впервые — суждение, которое не может сделать ни один рейтинг. Именно поэтому поиск возвращает описания, а не внедряет победителя.

• Агент ищет снова по мере развития задачи. Ни «autoscale», ни «pods» не появлялись в том, что просил пользователь.

Установка

pip install "skill-retrieval-mcp[local,hf]"
skill-mcp pull --include-index      # corpus + pre-built vector index
skill-mcp init                      # detect and register with your agents

Около двух минут, в основном загрузка. init находит установленных у вас агентов и сам записывает их конфигурацию.

init сам записывает .mcp.json, ~/.gemini/settings.json, .cursor/mcp.json и ~/.codex/config.toml. Для OpenClaw и Hermes он вызывает их собственный mcp add, потому что оба хранят MCP-серверы внутри более крупного конфигурационного файла, редактируемого вручную, и повторная сериализация здесь потеряла бы ваши комментарии. У DeepSeek Harness нет mcp add, поэтому init выводит строку, которую вы можете вставить сами.

Если он пропустил вашего агента, зарегистрируйте эту запись самостоятельно:

{
  "mcpServers": {
    "skill-retrieval": {
      "command": "/absolute/path/to/skill-mcp",
      "args": ["--data-dir", "/absolute/path/to/data-dir", "serve"]
    }
  }
}

Две детали имеют решающее значение, и обе молча выходят из строя, если их сократить:

• command должен быть абсолютным путём, а не skill-mcp. Агент сам разрешает имя из сессии, чей PATH обычно никогда не видел каталог venv или pipx, в который вы установили. which skill-mcp даст вам значение.

• --data-dir должен быть указан полностью и должен идти перед serve. ~ повторно разрешается в том окружении, из которого агент запускает сервер, а конфигурация, фиксирующая ваш выбор, живёт внутри выбранного каталога, так что ничто другое не может её восстановить. Сервер, открытый в неправильном каталоге, запускается чисто, перечисляет свои инструменты и отвечает на каждый поиск ничем. skill-mcp status выводит разрешённый каталог для использования.

Related MCP server: skill-curator-mcp

Почему поиск вместо установки

Установка навыков вручную работает, пока не перестаёт масштабироваться:

• Вы не знаете, что существует. Вы устанавливаете десять, которые случайно нашли. Обо всём остальном агент догадывается.

• Нельзя установить то, что не можешь назвать. В середине задачи агенту нужен навык для «публикации PyPI на основе OIDC» — вы бы никогда не подумали его добавить.

• Библиотека навыков не помещается в промпт. Ленивая загрузка всё равно помещает имя и описание каждого навыка перед моделью: 37K токенов для этой коллекции, прежде чем она прочитает хотя бы один. Сами инструкции — ещё 960K.

На 43 отложенных запросах, сформулированных так, как агент сформулировал бы задачу — никогда не повторяя имя самого навыка — поставляемая коллекция отвечает 81,4% на ранге 1 и 90,7% в пределах топ-3. Тестовый стенд находится в репозитории; см. dev.md для того, что он измеряет и что обнаружил.

Что в коллекции

374 навыка из восьми репозиториев, чьи лицензии были прочитаны до импорта чего-либо:

Каждый навык — это пошаговое руководство с примерами кода, подводными камнями и рекомендациями, а не однострочник. Медианный размер — около 9600 символов.

Каждая строка записывает репозиторий, из которого она взята, её вышестоящий URL и SPDX-лицензию, так что всё, что вы получаете, можно проследить и атрибутировать. Репозитории без лицензии, разрешающей распространение, не импортируются, каким бы хорошим ни был контент.

skill-mcp status показывает, что у вас есть локально.

Инструменты

Поиск возвращает только сводки. Агент вызывает get_skill для тех, которые ему действительно нужны, — именно здесь и возникает экономия токенов.

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

<!-- ~/my-skills/deploy-checklist/SKILL.md -->
---
name: "deploy-checklist"
description: "Pre-deployment verification checklist for production releases"
tags: ["deployment", "production", "checklist"]
---

## Steps

1. Run full test suite...
2. Check database migrations...

skill-mcp import --source directory --path ~/my-skills/

Индекс обновляется автоматически — новые навыки доступны для поиска немедленно, и встраиваются только новые. Передайте --no-index, чтобы пропустить это при пакетном импорте нескольких источников перед одной сборкой. Ваши навыки объединяются с коллекцией; дедупликация автоматическая.

Конфигурация

Всё хранится в одном каталоге данных, по умолчанию ~/.skill-mcp:

~/.skill-mcp/
├── config.yaml
├── skills.db          # SQLite + FTS5
└── index/             # FAISS

Укажите другое место с помощью глобального флага --data-dir или SKILL_MCP_DATA_DIR. Флаг принадлежит группе, поэтому он идёт перед подкомандой:

skill-mcp --data-dir /srv/skills pull

Бэкенды встраивания

По умолчанию используется sentence-transformers/all-MiniLM-L6-v2 — локальный, бесплатный, без ключа API, и именно на нём построен предварительно собранный индекс.

Индекс действителен только для модели, которая его построила, поэтому переключение означает пересборку:

# set backend: openai, model: text-embedding-3-large in config.yaml, then
skill-mcp build-index --backend openai

Справочник CLI

skill-mcp [--data-dir DIR] [--log-level LEVEL] COMMAND [ARGS]

  init [--data-dir DIR] [--no-register]        Set up the data directory, register with agents
  pull [--replace] [--include-index]           Download the corpus from HuggingFace
  import --source SOURCE --path PATH           Import your own skills
       [--no-index]
  build-index [--backend B] [--model M]        Build or update the vector index
       [--force]
  serve [--transport stdio|sse]                Start the MCP server
  search QUERY [--k N]                         Search from the terminal
  status                                       Show what is loaded
  dedup                                        Remove cross-source duplicates

Участие

Приветствуются вопросы и pull request'ы на github.com/JayCheng113/skill-retrieval-mcp. dev.md документирует архитектуру и обоснование дизайнерских решений, включая то, что было опробовано и отклонено — прочитайте его перед нетривиальным изменением.

Чтобы предложить репозиторий для коллекции, откройте issue с его лицензией и обоснованием того, что он покрывает, чего не покрывают текущие 374. Планка описана в dev.md: лицензия, разрешающая распространение, и доказательство того, что навыки действительно выигрывают запросы.

git clone https://github.com/JayCheng113/skill-retrieval-mcp
cd skill-retrieval-mcp
pip install -e ".[all,dev]"
pytest tests/ -v    # 240 tests, ~6s

Лицензия

MIT — см. LICENSE.