**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
[](https://skills-mcp-jignesh.vercel.app/)
[](LICENSE)
[](https://python.org)
[](https://workers.cloudflare.com)
[](skill_mcp/skills_data/)
[](https://glama.ai/mcp/servers/Jignesh-Ponamwar/skills-mcp)
[](https://deploy.workers.cloudflare.com/?url=https://github.com/Jignesh-Ponamwar/skills-mcp)
---
## 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 automation |
| `terraform` | IaC for AWS/GCP/Azure modules, remote state, workspaces, CI/CD integration |
### 🌐 Web and Fullstack Frameworks
| Skill | What it does |
|-------|-------------|
| `nextjs-best-practices` | App Router RSC, async params, data fetching, image/font optimization, self-hosting |
| `react-best-practices` | Hooks patterns, state management, memoization, virtualization, error boundaries |
| `fastapi` | Python REST APIs Pydantic v2, dependency injection, JWT auth, async SQLAlchemy, testing |
| `graphql-api` | Schema design, resolvers, DataLoader (N+1 prevention), Apollo Client, Strawberry |
| `typescript-patterns` | Generics, discriminated unions, branded types, conditional types, strict tsconfig |
### 🔌 Services and Integrations
| Skill | What it does |
|-------|-------------|
| `stripe-integration` | Checkout Sessions, webhooks, subscriptions, Connect (Accounts v2), security checklist |
| `supabase-integration` | PostgreSQL queries, auth (OAuth/magic link), RLS policies, real-time, storage |
### 🎨 Design and UI
| Skill | What it does |
|-------|-------------|
| `frontend-design` | Aesthetic direction, typography systems, color palettes, micro-animations, anti-patterns |
| `web-artifacts-builder` | Self-contained interactive HTML/React/Tailwind/D3 artifacts and dashboards |
---
## Setup
### What you need
| Requirement | Cost | Notes |
|-------------|------|-------|
| [Qdrant Cloud](https://cloud.qdrant.io) | Free | 1 GB free cluster - create one, copy URL + API key |
| [Cloudflare](https://cloudflare.com) | **Free** | Workers Free plan supports SQLite-backed Durable Objects |
| Python 3.11+ | Free | For the seed script and optional local server |
| Node.js 18+ | Free | For the `wrangler` CLI |
> **Cloudflare is free.** skills-mcp uses SQLite-backed Durable Objects (`new_sqlite_classes` in `wrangler.jsonc`), which are available on the Cloudflare Workers **Free** plan (100k requests/day). You only need the $5/mo paid plan if you outgrow that limit or need KV-backed Durable Objects.
### Quick Deploy (one click)
[](https://deploy.workers.cloudflare.com/?url=https://github.com/Jignesh-Ponamwar/skills-mcp)
Click the button above to deploy the Worker to your Cloudflare account. The deploy flow will prompt you for your **Qdrant Cloud URL** and **API key** (get both free at [cloud.qdrant.io](https://cloud.qdrant.io)). After the Worker is live, seed Qdrant with the bundled skills:
```bash
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
```
Your server is ready at `https://skill-mcp.