Skills Mcp

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 openSKILL.mdformat · Semantic discovery · Progressive loading · 30+ bundled skills · Self-hosted on Cloudflare

AI agents have broad knowledge, but narrow expertise.

The agent isn't making mistakes from lack of knowledge — it's missingthe 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-mcptakes 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 inSKILL.mdfiles live in one registry that agents discover and loadat 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.

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.

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 thefullskill 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.

Your Skills registry lives onCloudflare 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.

Seven MCP tools - 3-tier progressive disclosure + browsing

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 onlydescription + trigger_phrases(~100 tokens), keeping the vector space semantically clean and search results relevant.

The Worker usesCloudflare 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.

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.

- 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)

- ✅7 MCP toolsfor 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

Without skills-mcp:Tell Claude to "review this code." It gives generic feedback.
With skills-mcp:Agent loadscode-reviewskill → 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 loadssql-query-writerskill → 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 loadsstripe-integrationskill → references the verification pattern, security checklist, go-live steps → implementation is correct.

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.

Cloudflare is free.skills-mcp uses SQLite-backed Durable Objects (new_sqlite_classesinwrangler.jsonc), which are available on the Cloudflare WorkersFreeplan (100k requests/day). You only need the $5/mo paid plan if you outgrow that limit or need KV-backed Durable Objects.

Click the button above to deploy the Worker to your Cloudflare account. The deploy flow will prompt you for yourQdrant Cloud URLandAPI key(get both free atcloud.qdrant.io). After the Worker is live, seed Qdrant with the bundled skills:

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 athttps://skill-mcp.<your-subdomain>.workers.dev/sse. Full walkthrough:SETUP.md

# 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

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

# 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

# Start everything: Qdrant + seed + MCP server docker compose up # Or in background docker compose up -d && docker compose logs -f server

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

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

Before connecting to any hosted skills-mcp instance you do not control:readTRANSPARENCY.md. Skill bodies load directly into your agent's context window from a third-party server. The hosted instance offered by this repo is a personal deployment with no SLA and no authentication. For production use or sensitive workloads, self-host.

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

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

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

Step 2 Install the master skill for your platform

Drop the right file into any project root and the agent will automatically follow the 3-tier skill workflow when to search, how to interpret scores, and when to load supplementary files.

After copying, replace the placeholder URL with your deployed Worker URL.

Per-platform install commands:master-skill/README.md

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

--- 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"

-

Description and triggers are what get embeddedwrite them to match how an agent would phrase the need, not how you'd name the skill."extract tables from a PDF"beats"pdf-skill".

Reference tier-3 files by name in the bodythe agent receives atier3_manifestlisting available files and fetches only what the instructions explicitly mention. Nothing is loaded speculatively.

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

The seed script is idempotent re-running updates existing skills without creating duplicates.

Prompt-injection defence (ingestion pipeline)

A maliciousSKILL.mdwith embedded instruction overrides could alter how agents behave after loading the skill body - turning the registry into a prompt-injection delivery mechanism.

Every skill is scanned byskill_mcp/security/prompt_injection.pybeforeit enters Qdrant - at seed time and in CI on every PR. Skills with CRITICAL or HIGH findings are blocked. The scanner uses pattern matching; semantic attacks that evade patterns are a known residual risk (seeTHREAT_MODEL.md).

Full threat model:THREAT_MODEL.md· Hosted instance trust model:TRANSPARENCY.md

skill_mcp/- the Python package. Everything the server needs at runtime lives here: Pydantic models (models/), Qdrant integration (db/), MCP tool implementations (tools/), the prompt-injection scanner (security/), the seed script (seed/), the local FastMCP entry point (server.py), and the skill registry itself (skills_data/). If you are adding a skill, editing a tool, or touching the data layer, you are working here.