skill-retrieval-mcp

Búsqueda semántica sobre un corpus de 374 habilidades de agente verificado por licencia, servido a tu agente de codificación a través de MCP. Se ejecuta localmente, responde en milisegundos de un solo dígito y no realiza ninguna llamada a API.

Funciona con Claude Code, Codex CLI, Gemini CLI, Cursor, OpenClaw, Hermes y cualquier agente compatible con 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

Ambas búsquedas son resultados reales del corpus incluido, no una ilustración. Tres cosas en él son todo el diseño:

• La búsqueda devuelve resúmenes, no instrucciones. Cinco resúmenes cuestan unos pocos cientos de tokens; la única habilidad que el agente realmente lee cuesta alrededor de 2.400.

• El primer resultado no siempre es el correcto. El agente eligió el #4 porque su descripción dice por primera vez — un juicio que ningún ranking puede hacer. Por eso la búsqueda devuelve descripciones en lugar de inyectar el ganador.

• El agente vuelve a buscar a medida que la tarea evoluciona. Ni "autoscale" ni "pods" aparecieron en lo que el usuario pidió.

Instalación

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

Unos dos minutos, principalmente descarga. init encuentra los agentes que tienes instalados y escribe su configuración por ti.

init escribe .mcp.json, ~/.gemini/settings.json, .cursor/mcp.json y ~/.codex/config.toml por sí mismo. Para OpenClaw y Hermes llama a su propio mcp add, porque ambos mantienen los servidores MCP dentro de una configuración más grande editada a mano y re-serializarla aquí eliminaría tus comentarios. DeepSeek Harness no tiene mcp add, así que init imprime la fila para que la pegues.

Si no detecta tu agente, registra esta entrada tú mismo:

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

Dos detalles son cruciales, y ambos fallan silenciosamente si los acortas:

• command tiene que ser una ruta absoluta, no skill-mcp. El agente resuelve el nombre por sí mismo, desde una sesión cuyo PATH normalmente nunca ha visto el venv o el directorio pipx donde instalaste. which skill-mcp te da el valor.

• --data-dir tiene que escribirse completo, y tiene que ir antes de serve. ~ se re-resuelve en el entorno desde el que el agente lanza el servidor, y la configuración que registra tu elección vive dentro del directorio elegido, así que nada más puede recuperarla. Un servidor abierto en el directorio equivocado arranca limpiamente, lista sus herramientas y responde a cada búsqueda con nada. skill-mcp status imprime el directorio resuelto a usar.

Related MCP server: skill-curator-mcp

Por qué buscar en lugar de instalar

Instalar habilidades a mano funciona, hasta que deja de escalar:

• No sabes qué existe. Instalas las diez que encuentras por casualidad. Todo lo demás, el agente lo adivina.

• No puedes instalar lo que no puedes nombrar. A mitad de tarea el agente necesita una habilidad para "publicación de PyPI basada en OIDC" — nunca se te habría ocurrido añadirla.

• Una biblioteca de habilidades no cabe en el prompt. La carga perezosa aún pone el nombre y la descripción de cada habilidad frente al modelo: 37K tokens para este corpus antes de que lea una sola. Las instrucciones son otros 960K.

En 43 consultas reservadas formuladas como un agente formularía una tarea — nunca repitiendo el nombre de una habilidad — el corpus incluido responde 81,4% en el rango 1 y 90,7% dentro de los 3 primeros. El arnés está en el repo; consulta dev.md para ver qué mide y qué encontró.

Qué hay en el corpus

374 habilidades de ocho repositorios cuyas licencias se leyeron antes de importar nada:

Cada habilidad es una guía paso a paso con ejemplos de código, trampas y recomendaciones — no una línea suelta. La mediana ronda los 9.600 caracteres.

Cada fila registra el repositorio del que proviene, su URL upstream y su licencia SPDX, para que cualquier cosa que obtengas pueda rastrearse y atribuirse. Los repositorios sin una licencia que permita la redistribución no se importan, por bueno que sea el contenido.

skill-mcp status muestra lo que tienes localmente.

Herramientas

La búsqueda devuelve solo resúmenes. El agente llama a get_skill para las que realmente quiere, que es de donde viene el ahorro de tokens.

Añadir tus propias habilidades

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

El índice se actualiza automáticamente — las nuevas habilidades son buscables de inmediato, y solo se incrustan las nuevas. Pasa --no-index para omitir eso cuando estés importando por lotes varias fuentes antes de una compilación. Tus habilidades se fusionan con el corpus; la deduplicación es automática.

Configuración

Todo vive en un directorio de datos, ~/.skill-mcp por defecto:

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

Apunta a otro lugar con el flag global --data-dir o SKILL_MCP_DATA_DIR. El flag pertenece al grupo, así que va antes del subcomando:

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

Backends de incrustación

El predeterminado es sentence-transformers/all-MiniLM-L6-v2 — local, gratuito, sin clave de API, y el que se usó para construir el índice precompilado.

Un índice solo es válido para el modelo que lo construyó, así que cambiar significa reconstruir:

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

Referencia 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

Contribuir

Las incidencias y las solicitudes de extracción son bienvenidas en github.com/JayCheng113/skill-retrieval-mcp. dev.md documenta la arquitectura y el razonamiento detrás de las decisiones de diseño, incluido lo que se probó y se rechazó — léelo antes de un cambio no trivial.

Para proponer un repositorio para el corpus, abre una incidencia con su licencia y un argumento de qué cubre que los 374 actuales no cubran. El listón está en dev.md: una licencia que permita la redistribución y evidencia de que las habilidades realmente ganan consultas.

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

Licencia

MIT — consulta LICENSE.