skills-mcp

<div align="center"> <a href="https://skills-mcp-jignesh.vercel.app/"> <img src="./Skills-MCP%20Minimal%20Logo.png" alt="Skills-MCP Logo" /> </a>

Agent Skills — delivered over MCP.
One shared, searchable skill library that any MCP agent loads at runtime, instead of bundling skill files into every tool, repo, and context.
Built on the open SKILL.md format · Semantic discovery · Progressive loading · 30+ bundled skills · Self-hosted on Cloudflare

</div>

---

The Problem

AI agents have broad knowledge, but narrow expertise.

The agent isn't making mistakes from lack of knowledge — it's missing the procedural playbook. It's like having a senior engineer who's never seen your company's runbooks.

Agent Skills solve the playbook problem, but they normally live as files on a single machine or inside one tool's plugin — so every new tool, repo, and teammate keeps its own copy, and there's no shared, always-available library your agents can consult on demand.

What if one registry could serve them all?

The Solution: the Agent Skills model, as a shared service

skills-mcp takes the Agent Skills model and makes it a shared, searchable service. The same expert procedures, domain best practices, verified patterns, and reference material you'd put in SKILL.md files live in one registry that agents discover and load at the moment they need them, over MCP — no per-tool file syncing, no dumping every skill into context.

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.

The agent doesn't improvise. It retrieves a versioned, authoritative playbook — the way a senior engineer pulls up the deployment runbook when something matters.

And you own the Skills library. Self-host it. Add your own procedures. Control what agents can access. Update it when API versions change. Your agents stay up-to-date without retraining or prompting.

---

How It Works

1. Natural Language Discovery

Your agent asks: "How do I write pytest tests for a FastAPI endpoint?"

The Skills registry searches its semantic index and returns ranked results:

• test-writer (0.84 match) ← "I write comprehensive test suites"
• fastapi (0.71 match) ← "I'm the FastAPI skill"

The agent reads the confidence scores and decides what to load.

2. Load Only What You Need

The agent finds test-writer is a strong match, so it loads the full skill:

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)

Notice: you get the full skill body in one call. No chaining N+1 requests. The agent reads what it got, then decides if it needs supporting reference docs or example scripts.

3. Progressive Loading (No Wasted Bandwidth)

Only load what the agent actually needs:

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

The agent never speculatively loads files. If the test-writer skill says "see PATTERNS.md for advanced mocking," the agent requests it. If it doesn't mention it, it stays on the server.

Result: Fast discovery, small payloads, smart caching.

4. Self-Hosted, Serverless

Your Skills registry lives on Cloudflare Workers — no servers to manage, no uptime monitoring, no database admin. Search queries run at the edge using Cloudflare Workers AI. It costs nothing until you scale. Skills are versioned and immutable.

---

Architecture

Six Qdrant collections one purpose each

| Collection | Vector | Contents | |-----------|--------|----------| | skill_frontmatter | ✅ 384-dim | Name, description, tags, trigger phrases the discovery layer | | skill_body | payload only | Full markdown instructions + system prompt addition | | skill_options | payload only | Config schema, variants, dependencies, limitations | | skill_references | payload only | Markdown reference docs bundled with the skill | | skill_scripts | payload only | Executable scripts (source stored server-side; never sent to agents) | | skill_assets | payload only | Templates and static output format resources |

Seven MCP tools - 3-tier progressive disclosure + browsing

| Tier | Tool | When to call | |------|------|-------------| | 1 | skills_find_relevant(query, top_k) | Always first - semantic search, returns ranked skills with scores | | 1 | skills_list_all(limit, offset) | Browse all skills without searching - useful for discovery | | 2 | skills_get_body(skill_id, version?) | After finding a match - full instructions + tier3_manifest; version pins to a specific release | | 2 | skills_get_options(skill_id) | Optional - config schema, variants, dependencies, limitations | | 3 | skills_get_reference(skill_id, filename) | Only when instructions reference a specific doc | | 3 | skills_run_script(skill_id, filename, input_data) | Only when instructions direct script execution | | 3 | skills_get_asset(skill_id, filename) | Only when instructions reference a specific template |

Why embed only the frontmatter?

Embedding the full SKILL.md as a single vector pollutes the search space with instruction prose text that was never meant to be searched. skills-mcp embeds only description + trigger_phrases (~100 tokens), keeping the vector space semantically clean and search results relevant.

Embeddings no model version drift

The Worker uses Cloudflare Workers AI (@cf/baai/bge-small-en-v1.5, 384-dim) for query-time embedding. The seed script calls the same model via the REST API. Seed-time and query-time vectors are directly comparable no local GPU, no embedding server, no drift.

---

What's Included

30+ skills distilled from official documentation — Anthropic, Google, Vercel, Stripe, Django, Vue.js, and more. These aren't generic guides; they're built directly from the source material, with links back to the originals.

Each skill includes:

• Complexity level (beginner → intermediate → advanced)
• Time estimate (how long to read & understand)
• Prerequisites (what you need to know first)
• Use cases (real scenarios where you'd use this)
• Source URL (always traced back to official docs)

Highlights:

• ✅ 7 MCP tools for discovery, loading, and optional supplementary content
• ✅ Dynamic skill browser (skills_list_all) — agents can browse without searching
• ✅ Enhanced metadata — agents know skill complexity before they load it

---

Real-World Use Cases

Use Case 1: Consistent Code Reviews

Without skills-mcp: Tell Claude to "review this code." It gives generic feedback.
With skills-mcp: Agent loads code-review skill → applies your org's checklist → returns CRITICAL/HIGH/MEDIUM/LOW ratings → provides fix snippets.

Use Case 2: Generate SQL Queries That Scale

Without skills-mcp: Agent writes a query that works on test data but N+1 fails on production.
With skills-mcp: Agent loads sql-query-writer skill → applies window function patterns, CTE optimizations, index suggestions → generates production-ready queries first time.

Use Case 3: Webhook Implementation Done Right

Without skills-mcp: Agent's Stripe webhook doesn't verify signatures or misses idempotency.
With skills-mcp: Agent loads stripe-integration skill → references the verification pattern, security checklist, go-live steps → implementation is correct.

Use Case 4: Multi-Framework Consistency

Without skills-mcp: React agent and Vue agent write patterns differently.
With skills-mcp: Both agents search the Skills registry → find their framework skill → follow the same best practices → consistent codebase.

---

Bundled Skills by Category

🔧 Core Development

| Skill | What it does | |-------|-------------| | api-integration | REST/GraphQL clients with auth, pagination, retries, error handling, and OpenAPI alignment | | code-review | Structured security + quality review with CRITICAL/HIGH/MEDIUM/LOW severity ratings and fix snippets | | data-analysis | EDA, cleaning, statistics, visualizations, and actionable insights from CSV/tabular data | | git-commit-writer | Conventional Commits from diffs type, scope, breaking changes, and co-authors | | readme-writer | Professional README.md with badges, usage, API docs, and contributing guide | | sql-query-writer | Optimized SQL window functions, CTEs, indexes, explain plans, and common anti-patterns | | test-writer | pytest, Jest, and Go test suites with full edge case coverage and mocking patterns | | web-scraper | Structured data extraction with rate limiting, pagination, and anti-bot handling |

🏗️ Backend Frameworks

| Skill | What it does | |-------|-------------| | django-web-framework | Django MVT pattern: models, views, ORM, migrations, auth, middleware, testing, deployment |

🎨 Frontend Frameworks

| Skill | What it does | |-------|-------------| | vue-framework | Vue.js 3: composition API, reactive data, components, router, state management (Pinia), templates |

📄 Documents and Office

| Skill | What it does | |-------|-------------| | docx-creator | Create and edit Word documents with python-docx tables, styles, headers, tracked changes | | pdf-processing | Extract text/tables, fill forms, merge/split PDFs full Tier 3 scripts and references | | pptx-creator | Build PowerPoint presentations with pptxgenjs charts, images, design principles | | xlsx-creator | Excel spreadsheets with openpyxl formulas, formatting, charts, financial model conventions |

🤖 AI and LLM Platforms

| Skill | What it does | |-------|-------------| | claude-api | Anthropic SDK: tool use, streaming, vision, prompt caching, extended thinking, batch | | gemini-api | Google Gemini API: multimodal, function calling, structured output, current models/SDKs | | openai-api | OpenAI: GPT-4o, tool use, structured output, DALL-E, Whisper, TTS, batch processing | | llm-prompt-engineering | Chain-of-thought, few-shot, structured output, agent system prompt design, anti-patterns | | mcp-server-builder | Build MCP servers with FastMCP (Python) or TypeScript SDK tools, resources, prompts |

☁️ Cloud Platforms and Infrastructure

| Skill | What it does | |-------|-------------| | cloudflare-workers | Workers, Pages, KV, D1, R2, Workers AI, Vectorize, Durable Objects, Wrangler | | docker-containerization | Production Dockerfiles, multi-stage builds, Docker Compose, security hardening | | github-actions | CI/CD workflows, matrix builds, caching, Docker publishing, release au