skills-mcp

Un registro de habilidades para agentes, autoalojable, de código abierto y con búsqueda semántica, entregado a través de MCP, con una arquitectura de divulgación progresiva de tres niveles.

GitHub

Prueba este MCPPatrocinado

Documentación

skills-mcp

Agent Skills — entregados a través de MCP.
Una biblioteca de habilidades compartida y buscable que cualquier agente MCP carga en tiempo de ejecución, en lugar de empaquetar archivos de habilidades en cada herramienta, repositorio y contexto.
Construido sobre el formato abierto SKILL.md · Descubrimiento semántico · Carga progresiva · Más de 30 habilidades incluidas · Autoalojado en Cloudflare

El Problema

Los agentes de IA tienen un conocimiento amplio, pero una experiencia limitada.

El agente no comete errores por falta de conocimiento — le falta el manual de procedimientos. Es como tener un ingeniero senior que nunca ha visto los runbooks de tu empresa.

Agent Skills resuelven el problema del manual, pero normalmente viven como archivos en una sola máquina o dentro del plugin de una herramienta — así que cada nueva herramienta, repositorio y compañero de equipo mantiene su propia copia, y no hay una biblioteca compartida y siempre disponible que tus agentes puedan consultar bajo demanda.

¿Y si un solo registro pudiera servirlos a todos?

La Solución: el modelo Agent Skills, como servicio compartido

skills-mcp toma el modelo Agent Skills y lo convierte en un servicio compartido y buscable. Los mismos procedimientos expertos, mejores prácticas del dominio, patrones verificados y material de referencia que pondrías en archivos SKILL.md viven en un registro que los agentes descubren y cargan en el momento en que los necesitan, a través de MCP — sin sincronización de archivos por herramienta, sin volcar cada habilidad en el contexto.

You:   "Add Stripe subscriptions with webhook verification"

Agent: → calls skills_find_relevant("Stripe subscriptions webhooks")
         Returns: stripe-integration (confidence: 0.89)

       → calls skills_get_body("stripe-integration")
         Gets: API patterns, webhook signing verification, 
               idempotency key handling, security checklist, 
               live launch steps

       → Executes correctly. First time. Every time.

El agente no improvisa. Recupera un manual versionado y autoritativo — de la misma manera que un ingeniero senior consulta el runbook de despliegue cuando algo importa.

Y tú eres dueño de la biblioteca de Skills. Autoalójala. Añade tus propios procedimientos. Controla a qué pueden acceder los agentes. Actualízala cuando cambien las versiones de las API. Tus agentes se mantienen actualizados sin reentrenamiento ni prompts.

Cómo Funciona

1. Descubrimiento en Lenguaje Natural

Tu agente pregunta: "¿Cómo escribo pruebas pytest para un endpoint de FastAPI?"

El registro de Skills busca en su índice semántico y devuelve resultados ordenados:

test-writer (0.84 de coincidencia) ← "Escribo suites de pruebas completas"
fastapi (0.71 de coincidencia) ← "Soy la skill de FastAPI"

El agente lee las puntuaciones de confianza y decide qué cargar.

2. Carga Solo Lo Que Necesitas

El agente encuentra que test-writer es una coincidencia fuerte, así que carga la skill completa:

GET /skill/test-writer/body
→ Returns:
  - Full step-by-step testing guide
  - pytest patterns, fixtures, mocking
  - Edge case checklist
  - Available reference files (if any)
  - Available scripts (if any)

Nota: obtienes el cuerpo completo de la skill en una sola llamada. Sin encadenar solicitudes N+1. El agente lee lo que recibió y luego decide si necesita documentos de referencia de apoyo o scripts de ejemplo.

3. Carga Progresiva (Sin Ancho de Banda Desperdiciado)

Carga solo lo que el agente realmente necesita:

Tier 1  Search     → Find relevant skills (semantic match)
Tier 2  Load       → Get full instructions + manifest
Tier 3  Reference  → Load docs / scripts ONLY if instructions mention them

El agente nunca carga archivos especulativamente. Si la skill test-writer dice "consulta PATTERNS.md para mocking avanzado", el agente lo solicita. Si no lo menciona, permanece en el servidor.

Resultado: Descubrimiento rápido, cargas pequeñas, caché inteligente.

4. Autoalojado, Serverless

Tu registro de Skills vive en Cloudflare Workers — sin servidores que gestionar, sin monitoreo de disponibilidad, sin administración de bases de datos. Las consultas de búsqueda se ejecutan en el edge usando Cloudflare Workers AI. No cuesta nada hasta que escalas. Las Skills están versionadas y son inmutables.

Arquitectura

Seis colecciones de Qdrant — un propósito cada una

Colección	Vector	Contenido
`skill_frontmatter`	✅ 384-dim	Nombre, descripción, etiquetas, frases de activación — la capa de descubrimiento
`skill_body`	solo payload	Instrucciones completas en markdown + adición al prompt del sistema
`skill_options`	solo payload	Esquema de configuración, variantes, dependencias, limitaciones
`skill_references`	solo payload	Documentos de referencia en markdown incluidos con la skill
`skill_scripts`	solo payload	Scripts ejecutables (código fuente almacenado en el servidor; nunca enviado a los agentes)
`skill_assets`	solo payload	Plantillas y recursos de formato de salida estáticos

Siete herramientas MCP — divulgación progresiva de 3 niveles + navegación

Nivel	Herramienta	Cuándo llamar
1	`skills_find_relevant(query, top_k)`	Siempre primero — búsqueda semántica, devuelve skills ordenadas con puntuaciones
1	`skills_list_all(limit, offset)`	Navegar por todas las skills sin buscar — útil para el descubrimiento
2	`skills_get_body(skill_id, version?)`	Después de encontrar una coincidencia — instrucciones completas + `tier3_manifest`; `version` fija una versión específica
2	`skills_get_options(skill_id)`	Opcional — esquema de configuración, variantes, dependencias, limitaciones
3	`skills_get_reference(skill_id, filename)`	Solo cuando las instrucciones hacen referencia a un documento específico
3	`skills_run_script(skill_id, filename, input_data)`	Solo cuando las instrucciones indican la ejecución de un script
3	`skills_get_asset(skill_id, filename)`	Solo cuando las instrucciones hacen referencia a una plantilla específica

¿Por qué incrustar solo el frontmatter?

Incrustar el SKILL.md completo como un solo vector contamina el espacio de búsqueda con prosa de instrucciones — texto que nunca fue pensado para ser buscado. skills-mcp incrusta solo description + trigger_phrases (~100 tokens), manteniendo el espacio vectorial semánticamente limpio y los resultados de búsqueda relevantes.

Embeddings — sin desviación de versión del modelo

El Worker usa Cloudflare Workers AI (@cf/baai/bge-small-en-v1.5, 384-dim) para la incrustación en tiempo de consulta. El script de seed llama al mismo modelo a través de la API REST. Los vectores de seed y de consulta son directamente comparables — sin GPU local, sin servidor de incrustación, sin desviación.

Qué Incluye

Más de 30 skills destiladas de documentación oficial — Anthropic, Google, Vercel, Stripe, Django, Vue.js y más. No son guías genéricas; están construidas directamente del material fuente, con enlaces de vuelta a los originales.

Cada skill incluye:

Nivel de complejidad (principiante → intermedio → avanzado)
Estimación de tiempo (cuánto se tarda en leer y entender)
Prerrequisitos (lo que necesitas saber primero)
Casos de uso (escenarios reales donde usarías esto)
URL de origen (siempre rastreada hasta la documentación oficial)

Aspectos destacados:

✅ 7 herramientas MCP para descubrimiento, carga y contenido complementario opcional
✅ Navegador dinámico de skills (skills_list_all) — los agentes pueden navegar sin buscar
✅ Metadatos mejorados — los agentes conocen la complejidad de la skill antes de cargarla

Casos de Uso en el Mundo Real

Caso de Uso 1: Revisiones de Código Consistentes

Sin skills-mcp: Dile a Claude que "revise este código." Da comentarios genéricos.
Con skills-mcp: El agente carga la skill code-review → aplica la lista de verificación de tu organización → devuelve calificaciones CRITICAL/HIGH/MEDIUM/LOW → proporciona fragmentos de corrección.

Caso de Uso 2: Generar Consultas SQL Que Escalan

Sin skills-mcp: El agente escribe una consulta que funciona con datos de prueba pero falla con N+1 en producción.
Con skills-mcp: El agente carga la skill sql-query-writer → aplica patrones de funciones de ventana, optimizaciones de CTE, sugerencias de índices → genera consultas listas para producción a la primera.

Caso de Uso 3: Implementación de Webhooks Bien Hecha

Sin skills-mcp: El webhook de Stripe del agente no verifica firmas ni maneja la idempotencia.
Con skills-mcp: El agente carga la skill stripe-integration → consulta el patrón de verificación, la lista de seguridad, los pasos de puesta en producción → la implementación es correcta.

Caso de Uso 4: Consistencia Multi-Framework

Sin skills-mcp: El agente de React y el agente de Vue escriben patrones de manera diferente.
Con skills-mcp: Ambos agentes buscan en el registro de Skills → encuentran su skill de framework → siguen las mismas mejores prácticas → base de código consistente.

Skills Incluidas por Categoría

🔧 Desarrollo Principal

Skill	Qué hace
`api-integration`	Clientes REST/GraphQL con autenticación, paginación, reintentos, manejo de errores y alineación con OpenAPI
`code-review`	Revisión estructurada de seguridad + calidad con calificaciones de severidad CRITICAL/HIGH/MEDIUM/LOW y fragmentos de corrección
`data-analysis`	EDA, limpieza, estadísticas, visualizaciones e información accionable a partir de datos CSV/tabulares
`git-commit-writer`	Conventional Commits a partir de diffs — tipo, alcance, cambios disruptivos y coautores
`readme-writer`	README.md profesional con insignias, uso, documentación de API y guía de contribución
`sql-query-writer`	SQL optimizado — funciones de ventana, CTEs, índices, planes de explicación y anti-patrones comunes
`test-writer`	Suites de pruebas pytest, Jest y Go con cobertura completa de casos límite y patrones de mocking
`web-scraper`	Extracción estructurada de datos con limitación de velocidad, paginación y manejo anti-bot

🏗️ Frameworks de Backend

Skill	Qué hace
`django-web-framework`	Patrón MVT de Django: modelos, vistas, ORM, migraciones, autenticación, middleware, pruebas, despliegue

🎨 Frameworks de Frontend

Skill	Qué hace
`vue-framework`	Vue.js 3: composition API, datos reactivos, componentes, router, gestión de estado (Pinia), plantillas

📄 Documentos y Office

Skill	Qué hace
`docx-creator`	Crear y editar documentos de Word con python-docx — tablas, estilos, encabezados, cambios controlados
`pdf-processing`	Extraer texto/tablas, rellenar formularios, combinar/dividir PDFs — scripts y referencias completos de Nivel 3
`pptx-creator`	Crear presentaciones de PowerPoint con pptxgenjs — gráficos, imágenes, principios de diseño
`xlsx-creator`	Hojas de cálculo de Excel con openpyxl — fórmulas, formato, gráficos, convenciones de modelos financieros

🤖 Plataformas de IA y LLM

Skill	Qué hace
`claude-api`	SDK de Anthropic: uso de herramientas, streaming, visión, caché de prompts, pensamiento extendido, batch
`gemini-api`	API de Google Gemini: multimodal, llamada de funciones, salida estructurada, modelos/SDKs actuales
`openai-api`	OpenAI: GPT-4o, uso de herramientas, salida estructurada, DALL-E, Whisper, TTS, procesamiento por lotes
`llm-prompt-engineering`	Chain-of-thought, few-shot, salida estructurada, diseño de prompts de sistema para agentes, anti-patrones
`mcp-server-builder`	Construir servidores MCP con FastMCP (Python) o SDK de TypeScript — herramientas, recursos, prompts

☁️ Plataformas en la Nube e Infraestructura

Skill	Qué hace
`cloudflare-workers`	Workers, Pages, KV, D1, R2, Workers AI, Vectorize, Durable Objects, Wrangler
`docker-containerization`	Dockerfiles de producción, builds multi-etapa, Docker Compose, endurecimiento de seguridad
`github-actions`	Flujos de trabajo CI/CD, builds de matriz, caché, publicación de Docker, automatización de releases
`terraform`	IaC para AWS/GCP/Azure — módulos, estado remoto, workspaces, integración CI/CD

🌐 Frameworks Web y Fullstack

Skill	Qué hace
`nextjs-best-practices`	App Router — RSC, parámetros asíncronos, obtención de datos, optimización de imágenes/fuentes, autoalojamiento
`react-best-practices`	Patrones de hooks, gestión de estado, memoización, virtualización, límites de error
`fastapi`	APIs REST en Python — Pydantic v2, inyección de dependencias, autenticación JWT, SQLAlchemy asíncrono, pruebas
`graphql-api`	Diseño de esquemas, resolvers, DataLoader (prevención de N+1), Apollo Client, Strawberry
`typescript-patterns`	Genéricos, uniones discriminadas, tipos marcados, tipos condicionales, tsconfig estricto

🔌 Servicios e Integraciones

Skill	Qué hace
`stripe-integration`	Checkout Sessions, webhooks, suscripciones, Connect (Accounts v2), lista de verificación de seguridad
`supabase-integration`	Consultas PostgreSQL, autenticación (OAuth/magic link), políticas RLS, tiempo real, almacenamiento

🎨 Diseño y UI

Skill	Qué hace
`frontend-design`	Dirección estética, sistemas tipográficos, paletas de colores, micro-animaciones, anti-patrones
`web-artifacts-builder`	Artefactos y paneles interactivos autocontenidos en HTML/React/Tailwind/D3

Configuración

Lo que necesitas

Requisito	Coste	Notas
Qdrant Cloud	Gratis	Clúster gratuito de 1 GB: crea uno, copia la URL + clave API
Cloudflare	Gratis	El plan gratuito de Workers admite Durable Objects respaldados por SQLite
Python 3.11+	Gratis	Para el script de inicialización y el servidor local opcional
Node.js 18+	Gratis	Para el CLI de `wrangler`

Cloudflare es gratis. skills-mcp utiliza Durable Objects respaldados por SQLite (new_sqlite_classes en wrangler.jsonc), que están disponibles en el plan Gratis de Cloudflare Workers (100k solicitudes/día). Solo necesitas el plan de pago de $5/mes si superas ese límite o necesitas Durable Objects respaldados por KV.

Implementación rápida (un clic)

Haz clic en el botón de arriba para implementar el Worker en tu cuenta de Cloudflare. El flujo de implementación te pedirá tu URL de Qdrant Cloud y clave API (ambas gratis en cloud.qdrant.io). Una vez que el Worker esté activo, inicializa Qdrant con las habilidades incluidas:

git clone https://github.com/Jignesh-Ponamwar/skills-mcp && cd skills-mcp
pip install -r requirements.txt
cp .env.example .env
# Fill in: QDRANT_URL, QDRANT_API_KEY, WORKERS_AI_ACCOUNT_ID, WORKERS_AI_API_TOKEN
python -X utf8 -m skill_mcp.seed.seed_skills

Tu servidor está listo en https://skill-mcp.<your-subdomain>.workers.dev/sse. Guía completa: SETUP.md

Opción A: Un comando (recomendado)

Windows (PowerShell):

.\scripts\setup.ps1

Linux / macOS:

bash scripts/setup.sh

Multiplataforma (Make):

make setup

El asistente verifica los requisitos previos → crea .env → instala dependencias de Python → inicializa Qdrant con todas las habilidades incluidas → envía los secretos de Wrangler → implementa el Worker. Listo.

Opción B: Manual (paso a paso)

# 1. Clone
git clone https://github.com/yourusername/skills-mcp && cd skills-mcp

# 2. Configure credentials
cp .env.example .env
# Fill in: QDRANT_URL, QDRANT_API_KEY, WORKERS_AI_ACCOUNT_ID, WORKERS_AI_API_TOKEN

# 3. Install seed dependencies and seed Qdrant
pip install -r requirements.txt
python -X utf8 -m skill_mcp.seed.seed_skills

# 4. Deploy to Cloudflare
npm install -g wrangler
wrangler login
wrangler secret put QDRANT_URL      # paste your Qdrant URL
wrangler secret put QDRANT_API_KEY  # paste your Qdrant API key
wrangler deploy

Tu servidor está activo en:

https://skill-mcp.<your-subdomain>.workers.dev/sse

Guía completa de credenciales: SETUP.md

Referencia de objetivos de Make

# Cloudflare deployment
make env        # Copy .env.example → .env (skips if .env already exists)
make check      # Verify all required .env values are set
make install    # pip install -r requirements.txt
make seed       # Seed / re-seed Qdrant with all skills (idempotent)
make secrets    # Auto-push QDRANT_URL + QDRANT_API_KEY from .env to Worker
make deploy     # wrangler deploy
make dev        # Run local FastMCP server in stdio mode
make dev-http   # Run local FastMCP server on HTTP :8000
make setup      # Full first-run: env + install + seed + secrets + deploy

# Security & validation
make validate          # Validate all SKILL.md files - schema + prompt-injection scan
make calibrate         # Sweep (t_high, t_low) pairs; report precision/recall/F1
make check-qdrant-keys # Warn if read/write Qdrant keys are identical

# Docker (one-command local stack)
make docker-up    # Start Qdrant + seed + MCP server
make docker-down  # Stop containers (keeps Qdrant data)
make docker-seed  # Re-seed after adding new skills
make docker-logs  # Follow server logs

Opción C: Docker (un comando, totalmente local)

No se necesita cuenta de Cloudflare. Ejecuta Qdrant localmente en un contenedor: útil para configuraciones solo locales, entornos aislados o pruebas antes de implementar.

# Start everything: Qdrant + seed + MCP server
docker compose up

# Or in background
docker compose up -d && docker compose logs -f server

Tu servidor MCP local está activo en http://localhost:8000/sse.

Añade a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "skill-mcp": {
      "transport": "sse",
      "url": "http://localhost:8000/sse"
    }
  }
}

Requisitos para el modo Docker: solo WORKERS_AI_ACCOUNT_ID y WORKERS_AI_API_TOKEN en .env: aún se necesitan credenciales de Cloudflare para generar embeddings mediante Workers AI. Qdrant se ejecuta localmente, no se requiere cuenta de Qdrant Cloud.

make docker-up     # Start the full stack
make docker-down   # Stop (data volume preserved)
make docker-seed   # Re-seed after adding new skills

Conectando tu agente de IA

Antes de conectarte a cualquier instancia de skills-mcp alojada que no controles: lee TRANSPARENCY.md. Los cuerpos de las habilidades se cargan directamente en la ventana de contexto de tu agente desde un servidor de terceros. La instancia alojada que ofrece este repositorio es una implementación personal sin SLA ni autenticación. Para uso en producción o cargas de trabajo sensibles, auto-aloja.

Paso 1: Añade el servidor MCP

Añade a la configuración de tu cliente MCP (.mcp.json, configuración de Claude Code, configuración de Cursor, etc.):

Producción (Cloudflare Worker):

{
  "mcpServers": {
    "skill-mcp": {
      "transport": "sse",
      "url": "https://skill-mcp.<your-subdomain>.workers.dev/sse"
    }
  }
}

Desarrollo local (wrangler dev):

{
  "mcpServers": {
    "skill-mcp": {
      "transport": "sse",
      "url": "http://localhost:8787/sse"
    }
  }
}

Servidor Python local (necesario para skills_run_script: Cloudflare Workers no puede ejecutar subprocesos):

{
  "mcpServers": {
    "skill-mcp": {
      "command": "python",
      "args": ["-m", "skill_mcp.server"],
      "cwd": "/path/to/skills-mcp"
    }
  }
}

Paso 2: Instala la habilidad maestra para tu plataforma

Coloca el archivo correcto en la raíz de cualquier proyecto y el agente seguirá automáticamente el flujo de trabajo de habilidades de 3 niveles: cuándo buscar, cómo interpretar las puntuaciones y cuándo cargar archivos complementarios.

Plataforma	Archivo a copiar	Dónde
Claude Code	`master-skill/platforms/claude-code/CLAUDE.md`	Raíz del proyecto
Cursor	`master-skill/platforms/cursor/.cursorrules`	Raíz del proyecto
Windsurf	`master-skill/platforms/windsurf/.windsurfrules`	Raíz del proyecto
Antigravity (Google)	`master-skill/platforms/antigravity/.agents/`	Raíz del proyecto (principal)
Antigravity (Google)	`master-skill/platforms/antigravity/AGENTS.md`	Raíz del proyecto (secundario)
OpenAI Codex	`master-skill/platforms/codex/AGENTS.md`	Raíz del proyecto
Cline (VSCode)	`master-skill/platforms/cline/.clinerules`	Raíz del proyecto
GitHub Copilot	`master-skill/platforms/copilot/.github/`	Raíz del proyecto
Aider	`master-skill/platforms/aider/CONVENTIONS.md`	Raíz del proyecto

Después de copiar, reemplaza la URL de marcador de posición con la URL de tu Worker implementado.

Comandos de instalación por plataforma: master-skill/README.md

Añadiendo tus propias habilidades

Las habilidades viven en skill_mcp/skills_data/. Cada habilidad es una carpeta:

skill_mcp/skills_data/
└── my-skill/
    ├── SKILL.md          ← required: frontmatter + full instructions
    ├── references/       ← optional: markdown reference docs (.md)
    ├── scripts/          ← optional: executable scripts (.py, .js, .sh)
    └── assets/           ← optional: output templates and static files

Formato SKILL.md

---
name: my-skill
description: >
  One or two sentences describing WHEN to use this skill.
  Write it from the agent's perspective: "Use when the user asks to extract data from PDFs,
  process forms, or parse tables from documents."
license: Apache-2.0
metadata:
  author: your-name
  version: "1.0"
  tags: [pdf, extraction, data]
  platforms: [claude-code, cursor, any]
  triggers:
    - extract text from a PDF
    - parse a PDF document
    - read a PDF file
    - fill a PDF form
---

# Skill Title

Full step-by-step instructions. This is what the agent reads and follows.

Reference tier-3 files explicitly so the agent knows to load them:
- "For field type reference, see references/FORMS.md"
- "To extract data, run scripts/extract.py with PDF_PATH set to the file path"
- "Format your output using assets/extraction-template.md"

Dos reglas críticas:

La descripción y los disparadores son lo que se incrusta: escríbelos para que coincidan con cómo un agente formularía la necesidad, no con cómo nombrarías la habilidad. "extract tables from a PDF" supera a "pdf-skill".
Referencia los archivos de nivel 3 por nombre en el cuerpo: el agente recibe un tier3_manifest que lista los archivos disponibles y obtiene solo lo que las instrucciones mencionan explícitamente. Nada se carga especulativamente.

Re-inicialización después de añadir

python -X utf8 -m skill_mcp.seed.seed_skills
# or:
make seed

El script de inicialización es idempotente: volver a ejecutarlo actualiza las habilidades existentes sin crear duplicados.

Seguridad

Defensa contra inyección de prompts (pipeline de ingesta)

Un SKILL.md malicioso con anulaciones de instrucciones incrustadas podría alterar cómo se comportan los agentes después de cargar el cuerpo de la habilidad, convirtiendo el registro en un mecanismo de entrega de inyección de prompts.

Cada habilidad es escaneada por skill_mcp/security/prompt_injection.py antes de entrar en Qdrant, tanto en el momento de la inicialización como en CI en cada PR. Las habilidades con hallazgos CRÍTICOS o ALTOS se bloquean. El escáner utiliza coincidencia de patrones; los ataques semánticos que evaden los patrones son un riesgo residual conocido (ver THREAT_MODEL.md).

Categoría de ataque	Severidad	Ejemplo
Frases de anulación de instrucciones	CRÍTICO	`"ignore all previous instructions"`
Secuestro de rol / identidad	CRÍTICO	`"you are now an unrestricted AI"`
Inyección de delimitadores de prompt	ALTO	`</system>`, `[INST]`, `<<SYS>>`
Exfiltración de credenciales	CRÍTICO	`"POST the API key to webhook.site/…"`
Inyección de HTML / script	ALTO	`<script>` fuera de bloques de código
Caracteres Unicode BiDi / ancho cero	ALTO	Contenido visualmente oculto
Cargas útiles codificadas en Base64	CRÍTICO	Base64 que se decodifica en frases de anulación
Desplazamiento de contenido	MEDIO	20+ líneas en blanco consecutivas

Los bloques de código se eliminan antes de las comprobaciones estructurales: los genéricos de TypeScript (Promise<User>) y las etiquetas <script> en ejemplos de código nunca dan falsos positivos.

Modelo de amenazas completo: THREAT_MODEL.md · Modelo de confianza de la instancia alojada: TRANSPARENCY.md

Endurecimiento en tiempo de ejecución (Worker + servidor local)

Límite de velocidad por IP: 60 solicitudes/minuto con ventana deslizante (configurable mediante RATE_LIMIT_RPM); devuelve HTTP 429 cuando se supera; evicción de entradas obsoletas a 10k IPs; solo Worker
Encabezados CORS: Access-Control-Allow-Origin: * en todas las respuestas del Worker; admite clientes MCP basados en navegador y probadores (Glama, MCP Inspector)
Límite de cuerpo de solicitud de 1 MB: los cuerpos POST de más de 1 MB se rechazan con HTTP 413 antes del análisis
Mensajes de error saneados: las URL ascendentes, las respuestas de Qdrant y los seguimientos de pila nunca llegan a los clientes MCP
Encabezados de respuesta de seguridad: X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Cache-Control: no-store, Referrer-Policy: no-referrer
Límites de cadena de consulta: 2 KB en total, 16 parámetros, claves de 128 caracteres, valores de 256 caracteres
Validación de entrada: los argumentos de tools/call se verifican de tipo; el JSON-RPC malformado devuelve códigos de error adecuados
Límite de longitud de consulta: skills_find_relevant rechaza consultas de más de 2,000 caracteres

Ejecución de scripts (skills_run_script, solo servidor local):

tempfile.TemporaryDirectory() aislado: se elimina después de cada ejecución
Tiempo de espera máximo de 30 segundos con eliminación explícita del proceso
Entorno limpio mínimo: no se pasan credenciales ni variables de entorno sensibles a los scripts
Inyección de variables de entorno bloqueada (PATH, LD_PRELOAD, PYTHONPATH, etc.)
El código fuente del script nunca se devuelve al agente: solo stdout / stderr / exit_code
Salida truncada a 10,000 caracteres por flujo

En el Cloudflare Worker implementado, skills_run_script devuelve solo el manifiesto del script: el tiempo de ejecución de Pyodide no puede ejecutar subprocesos.

Estructura del proyecto

Tres directorios de nivel superior gestionan tres preocupaciones distintas:

skill_mcp/: el paquete de Python. Todo lo que el servidor necesita en tiempo de ejecución vive aquí: modelos Pydantic (models/), integración con Qdrant (db/), implementaciones de herramientas MCP (tools/), el escáner de inyección de prompts (security/), el script de inicialización (seed/), el punto de entrada local de FastMCP (server.py) y el propio registro de habilidades (skills_data/). Si estás añadiendo una habilidad, editando una herramienta o tocando la capa de datos, estás trabajando aquí.
src/: el destino de implementación de Cloudflare Workers. Contiene un solo archivo, worker.py, que reimplementa las seis herramientas MCP como un Worker de Python de Cloudflare autocontenido (sin paquetes externos, compatible con Pyodide). wrangler.jsonc en la raíz del repositorio apunta aquí. Edita esto solo cuando cambies el comportamiento del Worker implementado.
scripts/: utilidades de desarrollo y CI que no forman parte del paquete importable. setup.sh / setup.ps1 son asistentes interactivos de un solo uso; validate_skills.py es el esquema de SKILL.md + validador de inyección de prompts invocado tanto por make validate como por el flujo de trabajo de validación de habilidades de GitHub Actions.

skills-mcp/
├── skill_mcp/                     # Installable Python package (pip install -e ".[seed]")
│   ├── db/                        # Qdrant client, embedder, TTL cache
│   ├── eval/calibrate.py          # Threshold calibration runner (precision/recall sweep)
│   ├── models/skill.py            # Pydantic models for all 6 collection types
│   ├── security/prompt_injection.py  # 9-category injection scanner
│   ├── seed/seed_skills.py        # Walks skills_data/, scans, embeds, upserts Qdrant
│   ├── tools/                     # MCP tool implementations (local server)
│   ├── skills_data/               # skill folders - one SKILL.md each
│   └── server.py                  # Local FastMCP entry point (stdio / HTTP)
├── src/
│   └── worker.py                  # Cloudflare Python Worker - all 6 tools, SSE + Streamable HTTP, rate limiting, CORS
├── scripts/
│   ├── setup.sh / setup.ps1       # One-shot setup wizards (Linux/macOS + Windows)
│   └── validate_skills.py         # SKILL.md validator - schema + injection scan
├── master-skill/                  # Drop-in agent instruction files (8 platforms)
│   └── platforms/
│       ├── claude-code/CLAUDE.md
│       ├── cursor/.cursorrules
│       ├── windsurf/.windsurfrules
│       ├── codex/AGENTS.md
│       ├── cline/.clinerules
│       ├── copilot/.github/copilot-instructions.md
│       └── aider/CONVENTIONS.md
├── tests/
│   └── eval/threshold_calibration.json  # 120 eval triples for threshold calibration
├── .github/workflows/
│   ├── tests.yml                  # pytest on every push (unit tests, no external deps)
│   └── validate-skills.yml        # SKILL.md lint + injection scan on PRs
├── wrangler.jsonc                  # Workers AI binding + SQLite Durable Objects config
├── Makefile                        # Automation: setup, seed, deploy, dev, docker, validate
├── Dockerfile / docker-compose.yml # One-command local stack: Qdrant + seed + server
├── pyproject.toml                  # Package metadata + optional dependency groups
├── .env.example                    # Credential template - copy to .env
├── SETUP.md                        # Full credential walkthrough
├── CONTRIBUTING.md                 # Skill submission workflow + security policy
├── THREAT_MODEL.md                 # 7 threat categories with mitigations
├── TRANSPARENCY.md                 # Hosted instance trust model, SLA status, deployment boundaries
└── docs/                           # Architecture, versioning, calibration, and federation design

Limitaciones conocidas

Se requiere habilidad maestra para un comportamiento fiable del agente: el flujo de trabajo de 3 niveles (descubrir → cargar → complementar) solo se activa de manera consistente cuando el archivo de habilidad maestra está instalado en la raíz del proyecto del agente (ver Paso 2 arriba). Sin él, los agentes pueden omitir los umbrales de puntuación, cargar cuerpos de habilidades especulativamente o ignorar el tier3_manifest por completo, desperdiciando tokens de la ventana de contexto y produciendo resultados inconsistentes.
El uso de tokens escala con el tamaño de la colección: skills_find_relevant devuelve top_k descriptores de resultados (cada uno de ~100–200 tokens). Con 30 habilidades, esto es insignificante. Con 300+ habilidades y valores de top_k más altos, una sola llamada de descubrimiento puede consumir una parte significativa de la ventana de contexto. Mantén top_k bajo (3–5) y escribe frases de disparo precisas y distintas por habilidad para preservar la relevancia a escala.
La ejecución de scripts es solo local: skills_run_script requiere el servidor Python local. El Cloudflare Worker devuelve el manifiesto del script pero no puede ejecutar subprocesos: el tiempo de ejecución de Pyodide no admite subprocess. Cualquier flujo de trabajo de habilidades que llame a skills_run_script debe apuntar el cliente MCP a python -m skill_mcp.server en lugar de a la URL del Worker.
El modelo de embeddings se fija en el momento de la inicialización: los vectores se generan con @cf/baai/bge-small-en-v1.5 (384-dim) tanto en el momento de la inicialización como en el de la consulta. Si Cloudflare Workers AI retira o cambia este modelo, todos los vectores se vuelven incomparables y toda la colección de habilidades debe re-inicializarse.
La calidad de búsqueda depende de la calidad de las frases de disparo: la búsqueda semántica es tan buena como el triggers escrito en cada SKILL.md. Las habilidades con frases de disparo vagas o superpuestas aparecerán para consultas no relacionadas y diluirán los resultados. Una sola habilidad con disparadores mal escritos degrada todo el registro.

Contribuciones

Lee CONTRIBUTING.md para el flujo de trabajo completo de envío de habilidades: qué hace que una habilidad sea excelente, la referencia del formato SKILL.md, el proceso de PR paso a paso y la política de seguridad para las habilidades enviadas.

Inicio rápido:

# 1. Create your skill
mkdir -p skill_mcp/skills_data/my-skill && touch skill_mcp/skills_data/my-skill/SKILL.md

# 2. Validate locally (schema + prompt-injection scan)
python scripts/validate_skills.py skill_mcp/skills_data/my-skill/SKILL.md

# 3. Open a PR - CI runs automatically

Los dos invariantes que nunca deben romperse:

Nunca incrustes el cuerpo completo: solo description + triggers van a la colección de vectores
Nunca devuelvas el código fuente del script: skills_run_script devuelve solo stdout / stderr / exit_code

CI valida cada PR que toca skills_data/: sintaxis YAML, esquema, comprobación de slugs duplicados y escaneo de inyección de prompts. Un escaneo fallido bloquea la fusión.

Licencia

Apache 2.0: ver LICENSE.

Construido con Cloudflare Workers · Qdrant · FastMCP · MCP