skills-mcp
Provides skills for building and deploying Cloudflare Workers, including Pages, KV, D1, R2, Workers AI, Vectorize, Durable Objects, and Wrangler.
Provides skills for Docker containerization, including production Dockerfiles, multi-stage builds, Docker Compose, and security hardening.
Provides skills for building Python REST APIs with FastAPI, including Pydantic v2, dependency injection, JWT auth, async SQLAlchemy, and testing.
Provides skills for CI/CD workflows with GitHub Actions, including matrix builds, caching, Docker publishing, and release automation.
Provides skills for using the Google Gemini API, including multimodal, function calling, structured output, and current models/SDKs.
Provides skills for GraphQL API design, including schema design, resolvers, DataLoader, Apollo Client, and Strawberry.
Provides skills for using the OpenAI API, including GPT-4o, tool use, structured output, DALL-E, Whisper, TTS, and batch processing.
Provides skills for React development, including hooks patterns, state management, memoization, virtualization, and error boundaries.
Provides skills for Stripe integration, including Checkout Sessions, webhooks, subscriptions, Connect, and security best practices.
Provides skills for Infrastructure as Code with Terraform for AWS/GCP/Azure, including modules, remote state, workspaces, and CI/CD integration.
Provides skills for TypeScript patterns, including generics, discriminated unions, branded types, conditional types, and strict tsconfig.
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 open SKILL.md format · Semantic discovery · Progressive loading · 30+ bundled skills · Self-hosted on Cloudflare
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?
Related MCP server: Agent Skills MCP
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 themThe 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 |
| ✅ 384-dim | Name, description, tags, trigger phrases the discovery layer |
| payload only | Full markdown instructions + system prompt addition |
| payload only | Config schema, variants, dependencies, limitations |
| payload only | Markdown reference docs bundled with the skill |
| payload only | Executable scripts (source stored server-side; never sent to agents) |
| payload only | Templates and static output format resources |
Seven MCP tools - 3-tier progressive disclosure + browsing
Tier | Tool | When to call |
1 |
| Always first - semantic search, returns ranked skills with scores |
1 |
| Browse all skills without searching - useful for discovery |
2 |
| After finding a match - full instructions + |
2 |
| Optional - config schema, variants, dependencies, limitations |
3 |
| Only when instructions reference a specific doc |
3 |
| Only when instructions direct script execution |
3 |
| 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 |
| REST/GraphQL clients with auth, pagination, retries, error handling, and OpenAPI alignment |
| Structured security + quality review with CRITICAL/HIGH/MEDIUM/LOW severity ratings and fix snippets |
| EDA, cleaning, statistics, visualizations, and actionable insights from CSV/tabular data |
| Conventional Commits from diffs type, scope, breaking changes, and co-authors |
| Professional README.md with badges, usage, API docs, and contributing guide |
| Optimized SQL window functions, CTEs, indexes, explain plans, and common anti-patterns |
| pytest, Jest, and Go test suites with full edge case coverage and mocking patterns |
| Structured data extraction with rate limiting, pagination, and anti-bot handling |
🏗️ Backend Frameworks
Skill | What it does |
| Django MVT pattern: models, views, ORM, migrations, auth, middleware, testing, deployment |
🎨 Frontend Frameworks
Skill | What it does |
| Vue.js 3: composition API, reactive data, components, router, state management (Pinia), templates |
📄 Documents and Office
Skill | What it does |
| Create and edit Word documents with python-docx tables, styles, headers, tracked changes |
| Extract text/tables, fill forms, merge/split PDFs full Tier 3 scripts and references |
| Build PowerPoint presentations with pptxgenjs charts, images, design principles |
| Excel spreadsheets with openpyxl formulas, formatting, charts, financial model conventions |
🤖 AI and LLM Platforms
Skill | What it does |
| Anthropic SDK: tool use, streaming, vision, prompt caching, extended thinking, batch |
| Google Gemini API: multimodal, function calling, structured output, current models/SDKs |
| OpenAI: GPT-4o, tool use, structured output, DALL-E, Whisper, TTS, batch processing |
| Chain-of-thought, few-shot, structured output, agent system prompt design, anti-patterns |
| Build MCP servers with FastMCP (Python) or TypeScript SDK tools, resources, prompts |
☁️ Cloud Platforms and Infrastructure
Skill | What it does |
| Workers, Pages, KV, D1, R2, Workers AI, Vectorize, Durable Objects, Wrangler |
| Production Dockerfiles, multi-stage builds, Docker Compose, security hardening |
| CI/CD workflows, matrix builds, caching, Docker publishing, release automation |
| IaC for AWS/GCP/Azure modules, remote state, workspaces, CI/CD integration |
🌐 Web and Fullstack Frameworks
Skill | What it does |
| App Router RSC, async params, data fetching, image/font optimization, self-hosting |
| Hooks patterns, state management, memoization, virtualization, error boundaries |
| Python REST APIs Pydantic v2, dependency injection, JWT auth, async SQLAlchemy, testing |
| Schema design, resolvers, DataLoader (N+1 prevention), Apollo Client, Strawberry |
| Generics, discriminated unions, branded types, conditional types, strict tsconfig |
🔌 Services and Integrations
Skill | What it does |
| Checkout Sessions, webhooks, subscriptions, Connect (Accounts v2), security checklist |
| PostgreSQL queries, auth (OAuth/magic link), RLS policies, real-time, storage |
🎨 Design and UI
Skill | What it does |
| Aesthetic direction, typography systems, color palettes, micro-animations, anti-patterns |
| Self-contained interactive HTML/React/Tailwind/D3 artifacts and dashboards |
Setup
What you need
Requirement | Cost | Notes |
Free | 1 GB free cluster - create one, copy URL + API key | |
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 |
Cloudflare is free. skills-mcp uses SQLite-backed Durable Objects (
new_sqlite_classesinwrangler.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)
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). 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_skillsYour server is ready at https://skill-mcp.<your-subdomain>.workers.dev/sse. Full walkthrough: SETUP.md
Option A One Command (recommended)
Windows (PowerShell):
.\scripts\setup.ps1Linux / macOS:
bash scripts/setup.shCross-platform (Make):
make setupThe wizard checks prerequisites → creates .env → installs Python deps → seeds Qdrant with all bundled skills → pushes Wrangler secrets → deploys the Worker. Done.
Option B Manual (step by step)
# 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 deployYour server is live at:
https://skill-mcp.<your-subdomain>.workers.dev/sseFull credential walkthrough: SETUP.md
Make targets reference
# 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 logsOption C - Docker (one command, fully local)
No Cloudflare account needed. Runs Qdrant locally in a container - useful for local-only setups, air-gapped environments, or testing before deploying.
# Start everything: Qdrant + seed + MCP server
docker compose up
# Or in background
docker compose up -d && docker compose logs -f serverYour local MCP server is live at http://localhost:8000/sse.
Add to your MCP client config:
{
"mcpServers": {
"skill-mcp": {
"transport": "sse",
"url": "http://localhost:8000/sse"
}
}
}Requirements for Docker mode: only WORKERS_AI_ACCOUNT_ID and WORKERS_AI_API_TOKEN in .env - Cloudflare credentials are still needed to generate embeddings via Workers AI. Qdrant runs locally, no Qdrant Cloud account required.
make docker-up # Start the full stack
make docker-down # Stop (data volume preserved)
make docker-seed # Re-seed after adding new skillsConnecting Your AI Agent
Before connecting to any hosted skills-mcp instance you do not control: read TRANSPARENCY.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.
Step 1 Add the MCP server
Add to your MCP client config (.mcp.json, Claude Code settings, Cursor settings, etc.):
Production (Cloudflare Worker):
{
"mcpServers": {
"skill-mcp": {
"transport": "sse",
"url": "https://skill-mcp.<your-subdomain>.workers.dev/sse"
}
}
}Local dev (wrangler dev):
{
"mcpServers": {
"skill-mcp": {
"transport": "sse",
"url": "http://localhost:8787/sse"
}
}
}Local Python server (needed for skills_run_script Cloudflare Workers cannot run subprocesses):
{
"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.
Platform | File to copy | Where |
Claude Code |
| Project root |
Cursor |
| Project root |
Windsurf |
| Project root |
Antigravity (Google) |
| Project root (primary) |
Antigravity (Google) |
| Project root (secondary) |
OpenAI Codex |
| Project root |
Cline (VSCode) |
| Project root |
GitHub Copilot |
| Project root |
Aider |
| Project root |
After copying, replace the placeholder URL with your deployed Worker URL.
Per-platform install commands: master-skill/README.md
Adding Your Own Skills
Skills live in skill_mcp/skills_data/. Each skill is a folder:
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 filesSKILL.md format
---
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"Two critical rules:
Description and triggers are what get embedded write 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 body the agent receives a
tier3_manifestlisting available files and fetches only what the instructions explicitly mention. Nothing is loaded speculatively.
Re-seed after adding
python -X utf8 -m skill_mcp.seed.seed_skills
# or:
make seedThe seed script is idempotent re-running updates existing skills without creating duplicates.
Security
Prompt-injection defence (ingestion pipeline)
A malicious SKILL.md with 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 by skill_mcp/security/prompt_injection.py before it 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 (see THREAT_MODEL.md).
Attack category | Severity | Example |
Instruction-override phrases | CRITICAL |
|
Role / identity hijacking | CRITICAL |
|
Prompt delimiter injection | HIGH |
|
Credential exfiltration | CRITICAL |
|
HTML / script injection | HIGH |
|
Unicode BiDi / zero-width chars | HIGH | Visually hidden content |
Base64 encoded payloads | CRITICAL | Base64 that decodes to override phrases |
Content displacement | MEDIUM | 20+ consecutive blank lines |
Code blocks are stripped before structural checks - TypeScript generics (Promise<User>) and <script> tags in code examples never false-positive.
Full threat model: THREAT_MODEL.md · Hosted instance trust model: TRANSPARENCY.md
Runtime hardening (Worker + local server)
Per-IP rate limiting - 60 requests/minute sliding window (configurable via
RATE_LIMIT_RPM); returns HTTP 429 when exceeded; stale entry eviction at 10k IPs; Worker-onlyCORS headers -
Access-Control-Allow-Origin: *on all Worker responses; supports browser-based MCP clients and testers (Glama, MCP Inspector)1 MB request body limit - POST bodies over 1 MB rejected with HTTP 413 before parsing
Sanitized error messages - upstream URLs, Qdrant responses, and stack traces never reach MCP clients
Security response headers -
X-Content-Type-Options: nosniff,X-Frame-Options: DENY,Cache-Control: no-store,Referrer-Policy: no-referrerQuery string limits - 2 KB total, 16 parameters, 128-char keys, 256-char values
Input validation -
tools/callarguments type-checked; malformed JSON-RPC returns proper error codesQuery length limit -
skills_find_relevantrejects queries over 2,000 characters
Script execution (skills_run_script, local server only):
Isolated
tempfile.TemporaryDirectory()- deleted after each run30-second hard timeout with explicit process kill
Minimal clean environment - no credentials or sensitive env vars passed to scripts
Blocked environment variable injection (
PATH,LD_PRELOAD,PYTHONPATH, etc.)Script source never returned to the agent - only
stdout / stderr / exit_codeOutput truncated at 10,000 characters per stream
In the deployed Cloudflare Worker, skills_run_script returns the script manifest only the Pyodide runtime cannot run subprocesses.
Project Structure
Three top-level directories own three distinct concerns:
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.src/- the Cloudflare Workers deployment target. Contains a single file,worker.py, which re-implements all six MCP tools as a self-contained Cloudflare Python Worker (no external packages, Pyodide-compatible).wrangler.jsoncat the repo root points here. Edit this only when changing the deployed Worker behaviour.scripts/- developer and CI utilities that are not part of the importable package.setup.sh/setup.ps1are one-shot interactive wizards;validate_skills.pyis the SKILL.md schema + prompt-injection validator invoked by bothmake validateand the GitHub Actions skill-validation workflow.
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 designKnown Limitations
Master skill required for reliable agent behavior - The 3-tier workflow (discover → load → supplement) only fires consistently when the master skill file is installed in the agent's project root (see Step 2 above). Without it, agents may skip score thresholds, load skill bodies speculatively, or ignore the
tier3_manifestentirely - wasting context window tokens and producing inconsistent results.Token usage scales with collection size -
skills_find_relevantreturnstop_kresult descriptors (each ~100–200 tokens). At 30 skills this is negligible. At 300+ skills with highertop_kvalues, a single discovery call can consume a meaningful share of the context window. Keeptop_klow (3–5) and write precise, distinct trigger phrases per skill to preserve relevance at scale.Script execution is local-only -
skills_run_scriptrequires the local Python server. The Cloudflare Worker returns the script manifest but cannot execute subprocesses - the Pyodide runtime does not supportsubprocess. Any skill workflow that callsskills_run_scriptmust point the MCP client atpython -m skill_mcp.serverinstead of the Worker URL.Embedding model is pinned at seed time - Vectors are generated with
@cf/baai/bge-small-en-v1.5(384-dim) at both seed time and query time. If Cloudflare Workers AI retires or changes this model, all vectors become incomparable and the entire skill collection must be re-seeded.Search quality depends on trigger phrase quality - Semantic search is only as good as the
triggerswritten in eachSKILL.md. Skills with vague or overlapping trigger phrases will surface for unrelated queries and dilute results. One skill with poorly-written triggers degrades the entire registry.
Contributing
Read CONTRIBUTING.md for the full skill submission workflow - what makes a great skill, the SKILL.md format reference, step-by-step PR process, and the security policy for submitted skills.
Quick start:
# 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 automaticallyThe two invariants that must never be broken:
Never embed the full body only
description + triggersgo into the vector collectionNever return script source
skills_run_scriptreturnsstdout / stderr / exit_codeonly
CI validates every PR that touches skills_data/: YAML syntax, schema, duplicate slug check, and prompt-injection scan. A failing scan blocks merge.
License
Apache 2.0 see LICENSE.
Built with Cloudflare Workers · Qdrant · FastMCP · MCP
Available Tools
7 toolsskills_find_relevantA
STEP 1 - Discover relevant skills. Call this FIRST at the start of any task to check whether the registry contains a curated skill that matches. Performs semantic vector search and returns ranked results with similarity scores.
Workflow after this call: • score > 0.6 → strong match - call skills_get_body with that skill_id • score 0.4–0.6 → possible match - inspect description before proceeding • score < 0.4 → no relevant skill - proceed without one
Query tips: be task-specific, not generic. 'write pytest unit tests for a Flask REST API' outperforms 'testing'. Describe what you are trying to accomplish, not what you want to find.
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| top_k | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description bears full responsibility. It describes a non-destructive semantic search returning ranked similarity scores. Lacks details like error handling or registry emptiness, but it is transparent enough for safe use.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first sentence, then workflow steps and tips. It is concise yet informative, using bullet points effectively. Minor redundancy could be trimmed, but overall efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's search nature, the description covers the core workflow and parameter usage. The existence of an output schema reduces the need to detail return values. It is sufficiently complete for an agent to execute correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but the description provides rich context for the 'query' parameter with examples and tips. However, 'top_k' is not explained beyond its default, leaving some ambiguity. Adequate but not exhaustive.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Discover relevant skills' via semantic vector search. It is clearly distinct from sibling tools (e.g., skills_get_body retrieves body, skills_list_all lists all), using specific verbs and context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Call this FIRST' and provides a detailed workflow with score thresholds (>0.6, 0.4–0.6, <0.4) and corresponding actions. Also gives query tips for better results, offering clear guidance on when and how to use the tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
skills_get_assetA
STEP 3c - Fetch a template or static resource bundled with a skill (markdown templates, config starters, example data files).
Two-phase use:
Call with filename='list' (default) to see the full asset manifest
Call again with the specific filename to fetch its content
Use the returned content as a starting template - adapt it to the specific task. Only call when skill instructions reference a specific asset file.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | No | list | |
| skill_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Describes the two-phase pattern and that it returns content for templates. No annotations provided, so description carries burden; it adds enough behavioral context for a read operation. Could mention idempotency but not needed.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three short paragraphs, structured with numbered steps, no wasted words. Front-loaded with purpose and clear instructions.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Complete for a 2-parameter tool with output schema. Covers when to call, how to use (two-phase), and what to do with content. No gaps given the simplicity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% but description explains filename default and 'list' behavior, and that skill_id is required. Adds meaning beyond schema for filename, though skill_id is self-explanatory.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches a template or static resource bundled with a skill, listing examples like markdown templates, config starters, and data files. It distinguishes from sibling tools like skills_get_body and skills_get_reference by focusing on assets.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicit two-phase usage: first call with filename='list' to see manifest, then fetch specific file. Also states 'Only call when skill instructions reference a specific asset file,' providing clear context. However, no explicit comparison with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
skills_get_bodyA
STEP 2 - Load full skill instructions. Call after skills_find_relevant once you have identified the best-matching skill_id.
Returns three fields: • instructions - expert step-by-step guidance; read and follow these • system_prompt_addition - optional context to add to your persona (may be empty) • tier3_manifest - lists available references, scripts, and assets by filename
After loading: apply the instructions. If tier3_manifest lists files that the instructions explicitly reference, fetch them with skills_get_reference, skills_run_script, or skills_get_asset. Most tasks are fully served by the instructions alone - do not load Tier 3 speculatively.
Version pinning: pass version='1.2' to pin to a specific skill version, or use the inline form skill_id='stripe-integration@1.2'. If the requested version is not found, the latest version is returned with a version_note explaining the fallback. Deprecated skills include a deprecation_notice field naming the replacement.
| Name | Required | Description | Default |
|---|---|---|---|
| version | No | ||
| skill_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It discloses return fields, version fallback behavior, deprecation notices, and warns against speculative loading. It could explicitly state read-only nature, but the description implies it's a safe load operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with bullet points and clear sections, front-loading the purpose and step. Slightly verbose but every sentence adds value; could be slightly more concise.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema, the description explains the three return fields and their roles. It also covers versioning, deprecation, and when to use sibling tools, making the tool's context complete for an AI agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description adds substantial meaning: explains skill_id as identifier, version parameter optional with default null, pinning via version or inline, and behavior when version not found. This goes well beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: it is STEP 2 to load full skill instructions after identifying the best-matching skill_id via skills_find_relevant. The verb 'load' and resource 'skill instructions' are specific, and it distinguishes itself from sibling tools by its step and usage context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly instructs when to use the tool (after skills_find_relevant) and when not to (do not load Tier 3 speculatively). It provides version pinning details and references sibling tools for fetching referenced files, offering clear guidance on alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
skills_get_optionsA
OPTIONAL STEP 2b - Load config schema, variants, and constraints for a skill. Call only when: (a) the user asks to customise skill behaviour, or (b) skills_get_body instructions mention configurable options.
Returns: config_schema (JSON Schema for parameters), variants (alternative skill modes), dependencies (required tools/packages), limitations (known constraints).
Do NOT call this by default - most tasks complete with skills_get_body alone.
| Name | Required | Description | Default |
|---|---|---|---|
| skill_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Lists all four return components (config_schema, variants, dependencies, limitations) and implies read-only operation ('load'), but does not explicitly state it has no side effects. With no annotations, this is sufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Concise, front-loaded with 'OPTIONAL STEP 2b', and structured with conditions and return description. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given one simple parameter and presence of an output schema, the description fully covers tool behavior, usage context, and return details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0% and the description does not elaborate on the single parameter 'skill_id', which may be unclear without context. The description fails to compensate for the lack of schema descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states the tool loads config schema, variants, and constraints for a skill. It is well-differentiated from siblings like skills_get_body by being optional and for customization.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly specifies the two conditions for calling (user customization or skills_get_body instructions mention configurable options) and advises against default use.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
skills_get_referenceA
STEP 3a - Fetch a reference document bundled with a skill (markdown files: checklists, policies, API specs, examples).
Two-phase use:
Call with filename='list' (default) to see the full reference manifest
Call again with the specific filename to fetch its content
Only call when: tier3_manifest from skills_get_body lists reference files AND the skill instructions explicitly name one. Do not load references speculatively.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | No | list | |
| skill_id | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description bears full burden. It discloses the two-phase interaction and reading behavior. Lacks explicit mention of idempotency or error handling, but is sufficiently transparent for a read operation.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, no wasted words. Structured as STEP 3a, two-phase, with condition. Front-loaded with purpose and ends with usage rule.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Covers key aspects: purpose, input semantics, usage condition, output existence (via output schema). Could mention output format but schema handles that. Complete for a straightforward tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, but description adds meaning: explains the 'list' default for filename and how it enables the two-phase workflow. Could clarify skill_id's role more, but compensates well overall.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it fetches a reference document bundled with a skill, specifying file types (markdown files: checklists, policies, etc.). The 'STEP 3a' prefix and differentiation from siblings like skills_get_body make the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states when to call: only when tier3_manifest lists reference files and skill instructions name one, with a clear directive not to load speculatively. The two-phase usage pattern is fully explained.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
skills_list_allA
BROWSING - Browse all 100+ available skills in the registry without semantic search.
Use this when you want to see what skills are available, understand the full breadth of the registry, or look for skills by browsing rather than searching.
Returns lightweight frontmatter for each skill (skill_id, name, tags, complexity_level, has_tier3) to keep token usage reasonable.
Supports pagination: use offset to skip results, limit to control batch size.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description carries the full burden. It discloses that the tool is read-only, returns lightweight frontmatter, and supports pagination. It does not hide any destructive or mutating behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise with clear sections, using a heading and bullet-like formatting. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and a simple tool with output schema, the description covers behavior, pagination, and return content. It is sufficient for an agent to use correctly, though additional info on rate limits or error handling could improve it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 0%, so description must compensate. It explains both parameters (limit and offset) in the context of pagination, adding meaning beyond defaults and types. However, it could be more explicit about acceptable ranges.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it's for browsing all 100+ skills without semantic search, using a verb (browse, list) and resource (skills registry). It distinguishes from siblings like skills_find_relevant by explicitly noting it is not for semantic search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use (to see available skills, understand breadth, browse) and implicitly when not to (instead of searching). It mentions pagination details but does not explicitly exclude other scenarios.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
skills_run_scriptA
STEP 3b - Execute a helper script bundled with a skill. Script source is NEVER returned - only stdout, stderr, and exit_code.
Two-phase use:
Call with filename='list' to see available scripts and their descriptions
Call with the specific filename (and optional input_data) to execute
input_data: key-value pairs passed to the script as environment variables. Scripts run sandboxed in an isolated temp directory with a 30-second hard timeout.
Only call when skill instructions direct you to run a specific script.
| Name | Required | Description | Default |
|---|---|---|---|
| filename | No | list | |
| skill_id | Yes | ||
| list_only | No | ||
| input_data | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Discloses key behaviors: script source never returned, only stdout/stderr/exit_code; sandboxed isolated temp directory; 30-second hard timeout. With no annotations, description fully carries the transparency burden.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Efficiently structured with phases and bullet points. No wasted words; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given output schema exists, description covers all needed aspects: purpose, usage protocol, behavioral constraints, parameter guidance. Complete for a script execution tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Adds meaning beyond schema: explains filename default 'list' triggers listing, input_data passed as env vars, list_only boolean. But doesn't detail skill_id or fully describe list_only behavior. Compensates for 0% schema coverage, but slight gaps remain.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clear verb-resource: 'Execute a helper script' with specific two-phase use. Distinguishes from sibling tools that are about finding, listing, getting assets, none of which execute scripts.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly states 'Only call when skill instructions direct you to run a specific script.' Describes two-phase protocol (list with filename='list', then execute with specific filename). Provides clear context on when to use and how to proceed.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
Each tool has a clearly distinct role in the skill workflow: discovery (skills_find_relevant), loading instructions (skills_get_body), optional configuration (skills_get_options), fetching references (skills_get_reference), assets (skills_get_asset), and running scripts (skills_run_script). There is no overlap.
All tools follow a consistent verb_noun pattern using snake_case: skills_find_relevant, skills_get_body, skills_get_options, skills_get_reference, skills_get_asset, skills_run_script. The prefix 'skills_' and verb 'get' (or 'find'/'run') are uniform.
Six tools is well-scoped for a skill registry MCP server. Each tool serves a necessary step in the skill lifecycle (discovery, retrieval, configuration, reference material, assets, execution) without redundancy.
The tool set covers the full skill workflow from discovery to execution, including optional configuration and tier-3 resources. There are no obvious gaps—every essential operation is addressed.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
A registry of 5,900+ peer-authored skills any MCP agent can search and load on demand.
Search and discover Agent Skills from the skills.sh registry. Powered by HAPI MCP server.
Governed AI agent skills — one library, distributed to devs and exposed to remote agents over MCP.
Search engine for AI agents to find MCP servers, A2A agents, and skills on their own.
Related MCP Servers
- AlicenseAqualityBmaintenanceA package manager for AI agents that connects LLMs to a global registry of capabilities, allowing them to autonomously discover, install, and learn new skills from a centralized repository.43MIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that makes Agent Skills available to any MCP-compatible agent through a declarative, package.json-based configuration, enabling team-shareable skill management and execution.4MIT
- FlicenseNot gradedqualityBmaintenanceA hierarchical MCP server for managing skill definitions with a browsable tree structure and full-text search. It allows AI agents to efficiently discover and use skills without consuming context tokens.
- AlicenseBqualityBmaintenanceA self-hosted registry and MCP server for reusable AI-agent skills that enables agents to discover, retrieve, and install skills with guardrails.57MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/Jignesh-Ponamwar/skills-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server