skill-retrieval-mcp

Semantische Suche über einen lizenzgeprüften Korpus von 374 Agenten-Fähigkeiten, bereitgestellt für deinen Coding-Agenten über MCP. Läuft lokal, antwortet im einstelligen Millisekundenbereich und macht keine API-Aufrufe.

Funktioniert mit Claude Code, Codex CLI, Gemini CLI, Cursor, OpenClaw, Hermes und jedem MCP-kompatiblen Agenten.

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

Beide Suchen sind echte Ausgaben aus dem mitgelieferten Korpus, keine Illustration. Drei Dinge darin sind das gesamte Design:

• Suche liefert Zusammenfassungen, keine Anweisungen. Fünf Zusammenfassungen kosten ein paar hundert Tokens; die eine Fähigkeit, die der Agent tatsächlich liest, kostet etwa 2.400.

• Der Top-Treffer ist nicht immer der richtige. Der Agent wählte #4, weil seine Beschreibung zum ersten Mal sagt – ein Urteil, das kein Ranking treffen kann. Deshalb gibt die Suche Beschreibungen zurück, anstatt den Gewinner einzusetzen.

• Der Agent sucht erneut, während sich die Aufgabe entwickelt. Weder „autoscale“ noch „pods“ erschienen in dem, was der Benutzer verlangte.

Installation

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

Ungefähr zwei Minuten, hauptsächlich Download. init findet die von dir installierten Agenten und schreibt deren Konfiguration für dich.

init schreibt .mcp.json, ~/.gemini/settings.json, .cursor/mcp.json und ~/.codex/config.toml selbst. Für OpenClaw und Hermes ruft es deren eigenes mcp add auf, da beide MCP-Server in einer größeren, handbearbeiteten Konfiguration speichern und eine erneute Serialisierung hier deine Kommentare verwerfen würde. DeepSeek Harness hat kein mcp add, also gibt init die Zeile zum Einfügen aus.

Falls es deinen Agenten übersieht, registriere diesen Eintrag selbst:

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

Zwei Details sind tragend, und beide scheitern still, wenn du sie kürzt:

• command muss ein absoluter Pfad sein, nicht skill-mcp. Der Agent löst den Namen selbst auf, aus einer Sitzung, deren PATH routinemäßig nie das venv- oder pipx-Verzeichnis gesehen hat, in das du installiert hast. which skill-mcp gibt dir den Wert.

• --data-dir muss ausgeschrieben werden und vor serve stehen. ~ wird in der Umgebung, aus der der Agent den Server startet, neu aufgelöst, und die Konfiguration, die deine Wahl speichert, befindet sich innerhalb des gewählten Verzeichnisses, sodass nichts anderes sie wiederherstellen kann. Ein Server, der im falschen Verzeichnis geöffnet wird, startet sauber, listet seine Tools auf und beantwortet jede Suche mit nichts. skill-mcp status gibt das aufgelöste Verzeichnis zur Verwendung aus.

Related MCP server: skill-curator-mcp

Warum Suche statt Installation

Das manuelle Installieren von Fähigkeiten funktioniert, bis es nicht mehr skaliert:

• Du weißt nicht, was existiert. Du installierst die zehn, die du zufällig findest. Alles andere errät der Agent.

• Du kannst nicht installieren, was du nicht benennen kannst. Mitten in der Aufgabe benötigt der Agent eine Fähigkeit für „OIDC-basiertes PyPI-Publishing“ – du hättest nie daran gedacht, sie hinzuzufügen.

• Eine Fähigkeitsbibliothek passt nicht in den Prompt. Lazy Loading legt trotzdem jeden Namen und jede Beschreibung der Fähigkeiten vor das Modell: 37K Tokens für diesen Korpus, bevor es eine einzige gelesen hat. Die Anweisungen sind weitere 960K.

Bei 43 zurückgehaltenen Abfragen, die so formuliert sind, wie ein Agent eine Aufgabe formulieren würde – ohne den eigenen Namen einer Fähigkeit zu wiederholen – antwortet der mitgelieferte Korpus mit 81.4% auf Rang 1 und 90.7% innerhalb der Top 3. Der Testrahmen ist im Repo; siehe dev.md für das, was er misst und was er herausgefunden hat.

Was im Korpus ist

374 Fähigkeiten aus acht Repositories, deren Lizenzen gelesen wurden, bevor etwas importiert wurde:

Jede Fähigkeit ist eine Schritt-für-Schritt-Anleitung mit Codebeispielen, Fallstricken und Empfehlungen – kein Einzeiler. Der Median umfasst etwa 9.600 Zeichen.

Jede Zeile erfasst das Repository, aus dem sie stammt, ihre Upstream-URL und ihre SPDX-Lizenz, sodass alles, was du zurückbekommst, nachverfolgt und zugeordnet werden kann. Repositories ohne eine Lizenz, die die Weiterverbreitung erlaubt, werden nicht importiert, egal wie gut der Inhalt ist.

skill-mcp status zeigt, was du lokal hast.

Werkzeuge

Die Suche gibt nur Zusammenfassungen zurück. Der Agent ruft get_skill für diejenigen auf, die er tatsächlich möchte, und genau dort kommt die Token-Ersparnis her.

Eigene Fähigkeiten hinzufügen

<!-- ~/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/

Der Index aktualisiert sich automatisch – neue Fähigkeiten sind sofort durchsuchbar, und nur die neuen werden eingebettet. Übergib --no-index, um das zu überspringen, wenn du mehrere Quellen vor einem Build stapelweise importierst. Deine Fähigkeiten werden mit dem Korpus zusammengeführt; die Deduplizierung erfolgt automatisch.

Konfiguration

Alles befindet sich in einem Datenverzeichnis, standardmäßig ~/.skill-mcp:

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

Zeige mit dem globalen --data-dir-Flag oder SKILL_MCP_DATA_DIR auf einen anderen Ort. Das Flag gehört zur Gruppe, also steht es vor dem Unterbefehl:

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

Einbettungs-Backends

Der Standard ist sentence-transformers/all-MiniLM-L6-v2 – lokal, kostenlos, ohne API-Schlüssel, und derjenige, mit dem der vorgefertigte Index erstellt wurde.

Ein Index ist nur für das Modell gültig, das ihn erstellt hat, also bedeutet ein Wechsel ein Neuaufbau:

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

CLI-Referenz

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

Mitwirken

Issues und Pull-Requests sind willkommen unter github.com/JayCheng113/skill-retrieval-mcp. dev.md dokumentiert die Architektur und die Gründe hinter den Designentscheidungen, einschließlich dessen, was versucht und verworfen wurde – lies es vor einer nicht-trivialen Änderung.

Um ein Repository für den Korpus vorzuschlagen, öffne ein Issue mit seiner Lizenz und einer Begründung, was es abdeckt, das die aktuellen 374 nicht abdecken. Die Messlatte steht in dev.md: eine Lizenz, die die Weiterverbreitung erlaubt, und Belege, dass die Fähigkeiten tatsächlich Abfragen gewinnen.

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

Lizenz

MIT – siehe LICENSE.