Skills Mcp

skills-mcp

---

问题

AI Agent 知识广博，但专业能力有限。

Agent 犯错并非因为缺乏知识，而是缺少流程操作手册。这就像一位资深工程师从未看过你们公司的操作手册。

Agent 技能可以解决操作手册的问题，但通常以文件形式存放在一台机器上，或存在某个工具的插件中——因此每个新工具、代码仓库和队友都有自己的副本，也没有一个共享且始终可用的库，供 Agent 按需查阅。

如果一个注册库就能服务所有 Agent 呢？

解决方案：将 Agent 技能模式打造为共享服务

skills-mcp 将 Agent 技能模式打造为一个共享、可搜索的服务。你会放入 SKILL.md 文件中的专家流程、领域最佳实践、经过验证的模式和参考资料，都存储在同一个注册库中，供 Agent 通过 MCP 在需要时发现并加载——无需在各工具间同步文件，也无需将所有技能一股脑塞进上下文。

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.

Agent 不再即兴发挥，而是获取有版本记录、权威可靠的操作手册——就像资深工程师在关键时刻查阅部署操作手册一样。

技能库由你掌控。 可自托管。添加自己的流程。控制 Agent 可以访问的内容。API 版本变更时更新技能库。无需重新训练或编写提示词，Agent 也能保持最新。

---

工作原理

1. 自然语言检索

你的 Agent 会询问：“如何为 FastAPI 端点编写 pytest 测试？”

技能注册库会搜索语义索引并返回排序后的结果：

• test-writer（匹配度 0.84）←“我会编写全面的测试套件”
• fastapi（匹配度 0.71）←“我是 FastAPI 技能”

Agent 会读取置信度分数，并决定要加载哪些技能。

2. 只加载所需内容

Agent 发现 test-writer 匹配度很高，于是加载完整技能：

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)

请注意：只需一次调用，就能获取技能的完整内容。无需串联 N+1 个请求。Agent 读取获取的内容后，再决定是否需要相关参考文档或示例脚本。

3. 渐进式加载（不浪费带宽）

只加载 Agent 实际需要的内容：

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

Agent 不会试探性地加载文件。如果 test-writer 技能提到“参见 PATTERNS.md，了解高级模拟”，Agent 就会请求该文件。如果没有提到，文件就会留在服务端。

结果： 快速检索、轻量载荷、智能缓存。

4. 自托管，无服务器

你的 Skills 注册表运行在 Cloudflare Workers 上——无需管理服务器、监控运行时间或管理数据库。搜索查询通过 Cloudflare Workers AI 在边缘运行。在扩展规模之前，完全免费。Skills 采用版本管理且不可变。

---

架构

六个 Qdrant 集合，各司其职

集合	向量	内容
skill_frontmatter	✅ 384 维	名称、描述、标签、触发短语——发现层
skill_body	仅载荷	完整的 Markdown 指令 + 系统提示词补充内容
skill_options	仅载荷	配置架构、变体、依赖项、限制
skill_references	仅载荷	随 Skill 打包的 Markdown 参考文档
skill_scripts	仅载荷	可执行脚本（源代码存储在服务端；绝不会发送给 Agent）
skill_assets	仅载荷	模板和静态输出格式资源

七个 MCP 工具——三级渐进式披露 + 浏览

级别	工具	调用时机
1	skills_find_relevant(query, top_k)	始终首先调用——语义搜索，返回带评分的排序 Skills
1	skills_list_all(limit, offset)	无需搜索即可浏览所有 Skills——有助于发现
2	skills_get_body(skill_id, version?)	找到匹配项后调用——完整指令 + tier3_manifest；version 可指定某个版本
2	skills_get_options(skill_id)	可选——配置架构、变体、依赖项、限制
3	skills_get_reference(skill_id, filename)	仅当指令引用了特定文档时调用
3	skills_run_script(skill_id, filename, input_data)	仅当指令要求执行脚本时调用
3	skills_get_asset(skill_id, filename)	仅当指令引用了特定模板时调用

为什么只嵌入 frontmatter？

将完整的 SKILL.md 作为单个向量嵌入，会让指令文本污染搜索空间——这些文本本就不该被搜索。skills-mcp 只嵌入 description + trigger_phrases（约 100 个词元），让向量空间在语义上保持纯净，搜索结果也更相关。

嵌入——无模型版本漂移

Worker 使用 Cloudflare Workers AI（@cf/baai/bge-small-en-v1.5，384 维）在查询时生成嵌入。种子脚本通过 REST API 调用同一模型。因此，种子阶段和查询阶段生成的向量可以直接比较——无需本地 GPU、嵌入服务器，也不会发生漂移。

---

包含内容

30 多个从官方文档提炼而来的 Skills，涵盖 Anthropic、Google、Vercel、Stripe、Django、Vue.js 等。这些并非通用指南，而是直接基于源材料构建，并附有指向原文的链接。

每个 Skill 都包含：

• 复杂度级别（初级 → 中级 → 高级）
• 时间估算（阅读和理解所需时间）
• 先决条件（需要预先了解的内容）
• 用例（实际使用场景）
• 来源 URL（始终可追溯至官方文档）

亮点：

• ✅ 7 个 MCP 工具，用于发现、加载和获取可选的补充内容
• ✅ 动态 Skill 浏览器（skills_list_all）——Agent 无需搜索即可浏览
• ✅ 增强的元数据——Agent 在加载 Skill 前即可了解其复杂度

---

实际应用场景

用例 1：保持代码审查的一致性

不使用 skills-mcp： 让 Claude“审查这段代码”。它只会给出通用反馈。
使用 skills-mcp： Agent 加载 code-review Skill → 应用你们组织的检查清单 → 返回 CRITICAL/HIGH/MEDIUM/LOW 评级 → 提供修复代码片段。

用例 2：生成可扩展的 SQL 查询

不使用 skills-mcp： Agent 编写的查询在测试数据上能正常工作，但在生产环境中会因 N+1 问题而失败。
使用 skills-mcp： Agent 加载 sql-query-writer Skill → 应用窗口函数模式、CTE 优化和索引建议 → 首次就生成适用于生产环境的查询。

用例 3：正确实现 Webhook

不使用 skills-mcp： Agent 的 Stripe webhook 未验证签名，或遗漏了幂等性处理。
使用 skills-mcp： Agent 加载 stripe-integration 技能 → 参考验证模式、安全检查清单和上线步骤 → 正确实现。

用例 4：多框架保持一致

不使用 skills-mcp： React Agent 和 Vue Agent 编写的模式各不相同。
使用 skills-mcp： 两个 Agent 都搜索 Skills 注册表 → 找到对应的框架技能 → 遵循相同的最佳实践 → 代码库保持一致。

---

按类别划分的内置技能

🔧 核心开发

技能	功能
api-integration	REST/GraphQL 客户端，支持身份验证、分页、重试、错误处理和 OpenAPI 对齐
code-review	结构化的安全性与质量审查，提供 CRITICAL/HIGH/MEDIUM/LOW 严重性评级和修复代码片段
data-analysis	对 CSV/表格数据执行 EDA、清理、统计分析、可视化，并提供可执行的见解
git-commit-writer	根据差异编写 Conventional Commits，涵盖类型、范围、破坏性变更和共同作者
readme-writer	编写专业的 README.md，包含徽章、用法、API 文档和贡献指南
sql-query-writer	编写优化的 SQL，涵盖窗口函数、CTE、索引、执行计划和常见反模式
test-writer	编写 pytest、Jest 和 Go 测试套件，全面覆盖边界情况并采用模拟模式
web-scraper	结构化数据提取，支持速率限制、分页和反机器人处理

🏗️ 后端框架

技能	功能
django-web-framework	Django MVT 模式：模型、视图、ORM、迁移、身份验证、中间件、测试和部署

🎨 前端框架

技能	功能
vue-framework	Vue.js 3：组合式 API、响应式数据、组件、路由器、状态管理（Pinia）和模板

📄 文档与办公软件

技能	功能
docx-creator	使用 python-docx 创建和编辑 Word 文档，支持表格、样式、页眉和修订
pdf-processing	提取文本/表格、填写表单、合并/拆分 PDF，包含完整的 Tier 3 脚本和参考资料
pptx-creator	使用 pptxgenjs 制作 PowerPoint 演示文稿，支持图表、图片和设计原则
xlsx-creator	使用 openpyxl 创建 Excel 电子表格，支持公式、格式设置、图表和财务模型规范

🤖 AI 和大模型平台

技能	功能
claude-api	Anthropic SDK：工具调用、流式传输、视觉、提示词缓存、扩展思考和批处理
gemini-api	Google Gemini API：多模态、函数调用、结构化输出、当前模型/SDK
openai-api	OpenAI：GPT-4o、工具调用、结构化输出、DALL-E、Whisper、TTS 和批处理
llm-prompt-engineering	思维链、少样本、结构化输出、Agent 系统提示词设计和反模式
mcp-server-builder	使用 FastMCP（Python）或 TypeScript SDK 构建 MCP 服务，支持工具、资源和提示词

☁️ 云平台与基础设施

技能	功能
cloudflare-workers	Workers、Pages、KV、D1、R2、Workers AI、Vectorize、Durable Objects 和 Wrangler
docker-containerization	生产级 Dockerfile、多阶段构建、Docker Compose 和安全加固
github-actions	CI/CD 工作流、矩阵构建、缓存、Docker 发布和版本发布自动化
terraform	用于 AWS/GCP/Azure 的 IaC，涵盖模块、远程状态、工作区和 CI/CD 集成

🌐 Web 和全栈框架

技能	功能
nextjs-best-practices	App Router、RSC、异步参数、数据获取、图像／字体优化、可自托管
react-best-practices	Hooks 模式、状态管理、记忆化、虚拟化、错误边界
fastapi	Python REST API、Pydantic v2、依赖注入、JWT 身份验证、异步 SQLAlchemy、测试
graphql-api	Schema 设计、解析器、DataLoader（防止 N+1）、Apollo Client、Strawberry
typescript-patterns	泛型、可辨识联合、品牌类型、条件类型、严格的 tsconfig

🔌 服务和集成

技能	功能
stripe-integration	Checkout Sessions、webhook、订阅、Connect（Accounts v2）、安全检查清单
supabase-integration	PostgreSQL 查询、身份验证（OAuth／magic link）、RLS 策略、实时功能、存储

🎨 设计和 UI

技能	功能
frontend-design	美学方向、排版系统、调色板、微动画、反模式
web-artifacts-builder	独立的交互式 HTML／React／Tailwind／D3 制品和仪表板

---

设置

所需条件

要求	费用	备注
Qdrant Cloud	免费	1 GB 免费集群——创建一个并复制 URL 和 API 密钥
Cloudflare	免费	Workers 免费计划支持由 SQLite 提供支持的 Durable Objects
Python 3.11+	免费	用于种子脚本和可选的本地服务
Node.js 18+	免费	用于 wrangler CLI

Cloudflare 免费。 skills-mcp 使用由 SQLite 提供支持的 Durable Objects（wrangler.jsonc 中的 new_sqlite_classes），Cloudflare Workers 免费计划（每天 100k 个请求）即可使用。只有超出此限制或需要由 KV 提供支持的 Durable Objects 时，才需要每月 5 美元的付费计划。

快速部署（一键）

点击上方按钮，将 Worker 部署到你的 Cloudflare 账户。部署流程会提示你输入 Qdrant Cloud URL 和 API 密钥（均可在 cloud.qdrant.io 免费获取）。Worker 上线后，使用捆绑的技能为 Qdrant 填充种子数据：

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

你的服务已就绪，地址为 https://skill-mcp.<your-subdomain>.workers.dev/sse。完整指南：SETUP.md

选项 A 一条命令（推荐）

Windows（PowerShell）：

.\scripts\setup.ps1

Linux / macOS：

bash scripts/setup.sh

跨平台（Make）：

make setup

向导会检查先决条件 → 创建 .env → 安装 Python 依赖 → 使用所有捆绑的技能为 Qdrant 填充种子数据 → 推送 Wrangler 密钥 → 部署 Worker。完成。

选项 B 手动操作（分步进行）

# 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

完整的凭据配置指南：SETUP.md

Make 目标参考

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

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

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

选项 C - Docker（一条命令，完全本地运行）

无需 Cloudflare 账户。在容器中本地运行 Qdrant，适用于仅限本地的设置、隔离网络环境或部署前测试。

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

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

你的本地 MCP 服务已上线，地址为 http://localhost:8000/sse。

添加到 MCP 客户端配置中：

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

Docker 模式的要求： .env 中只需设置 WORKERS_AI_ACCOUNT_ID 和 WORKERS_AI_API_TOKEN——仍需要 Cloudflare 凭据，以便通过 Workers AI 生成嵌入向量。Qdrant 在本地运行，无需 Qdrant Cloud 账户。

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

---

连接你的 AI Agent

**在连接任何你无权控制的托管 skills-mcp 实例之前：**请阅读 TRANSPARENCY.md。技能内容会从第三方服务直接加载到你的 Agent 上下文窗口中。本仓库提供的托管实例是个人部署，没有 SLA，也未进行身份验证。用于生产环境或敏感工作负载时，请自行托管。

步骤 1 添加 MCP 服务

在 MCP 客户端配置中（.mcp.json、Claude Code 设置、Cursor 设置等）添加：

生产环境（Cloudflare Worker）：

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

本地开发（wrangler dev）：

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

本地 Python 服务（skills_run_script 所需——Cloudflare Workers 无法运行子进程）：

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

步骤 2 为你的平台安装主技能

将对应文件放入任意项目根目录，Agent 就会自动遵循三级技能工作流——何时搜索、如何解读评分，以及何时加载补充文件。

平台	要复制的文件	位置
Claude Code	master-skill/platforms/claude-code/CLAUDE.md	项目根目录
Cursor	master-skill/platforms/cursor/.cursorrules	项目根目录
Windsurf	master-skill/platforms/windsurf/.windsurfrules	项目根目录
Antigravity（Google）	master-skill/platforms/antigravity/.agents/	项目根目录（主要）
Antigravity（Google）	master-skill/platforms/antigravity/AGENTS.md	项目根目录（次要）
OpenAI Codex	master-skill/platforms/codex/AGENTS.md	项目根目录
Cline（VSCode）	master-skill/platforms/cline/.clinerules	项目根目录
GitHub Copilot	master-skill/platforms/copilot/.github/	项目根目录
Aider	master-skill/platforms/aider/CONVENTIONS.md	项目根目录

复制后，将占位 URL 替换为已部署的 Worker URL。

各平台的安装命令：master-skill/README.md

---

添加你自己的技能

技能位于 skill_mcp/skills_data/。每个技能都是一个文件夹：

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

SKILL.md 格式

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

# Skill Title

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

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

两条重要规则：

1. 描述和触发条件会被嵌入——编写时应贴近 Agent 描述需求的方式，而不是技能的命名方式。"extract tables from a PDF" 比 "pdf-skill" 更合适。

2. 在正文中按名称引用第 3 层文件——Agent 会收到列出可用文件的 tier3_manifest，并且只会获取指令明确提及的文件。不会进行推测性加载。

添加后重新填充数据

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

种子脚本具有幂等性——重新运行会更新现有技能，不会创建重复项。

---

安全

提示词注入防御（摄取流水线）

包含嵌入式指令覆盖内容的恶意 SKILL.md，可能会在加载技能正文后改变 Agent 的行为——使注册表沦为提示词注入的投递机制。

每个技能在进入 Qdrant 之前，都会由 skill_mcp/security/prompt_injection.py 扫描——在填充数据时扫描，并在 CI 中对每个 PR 进行扫描。检测到 CRITICAL 或 HIGH 级别问题的技能会被拦截。扫描器使用模式匹配；能够绕过模式的语义攻击是已知的残余风险（参见 THREAT_MODEL.md）。

攻击类别	严重性	示例
指令覆盖短语	CRITICAL	"ignore all previous instructions"
角色／身份劫持	CRITICAL	"you are now an unrestricted AI"
提示词分隔符注入	HIGH	</system>、[INST]、<<SYS>>
凭据窃取	CRITICAL	"POST the API key to webhook.site/…"
HTML／脚本注入	HIGH	代码块之外的 <script>
Unicode 双向控制符／零宽字符	HIGH	视觉上隐藏的内容
Base64 编码载荷	CRITICAL	解码后包含指令覆盖短语的 Base64
内容位移	MEDIUM	连续 20 行以上的空行

结构检查前会先移除代码块——TypeScript 泛型（Promise<User>）和代码示例中的 <script> 标签都不会造成误报。

完整威胁模型：THREAT_MODEL.md · 托管实例信任模型：TRANSPARENCY.md

运行时加固（Worker + 本地服务）

• 按 IP 限流 - 滑动窗口每分钟 60 个请求（可通过 RATE_LIMIT_RPM 配置）；超出时返回 HTTP 429；IP 数量达到 10k 时清理过期条目；仅适用于 Worker
• CORS 标头 - 所有 Worker 响应均包含 Access-Control-Allow-Origin: *；支持基于浏览器的 MCP 客户端和测试工具（Glama、MCP Inspector）
• 1 MB 请求正文限制 - 超过 1 MB 的 POST 正文会在解析前被拒绝，并返回 HTTP 413
• 错误消息脱敏 - 上游 URL、Qdrant 响应和堆栈跟踪不会泄露给 MCP 客户端
• 安全响应标头 - X-Content-Type-Options: nosniff、X-Frame-Options: DENY、Cache-Control: no-store、Referrer-Policy: no-referrer
• 查询字符串限制 - 总长度 2 KB，最多 16 个参数，键最长 128 个字符，值最长 256 个字符
• 输入验证 - 对 tools/call 参数进行类型检查；格式错误的 JSON-RPC 会返回正确的错误代码
• 查询长度限制 - skills_find_relevant 会拒绝超过 2,000 个字符的查询

脚本执行（仅限本地服务的 skills_run_script）：

• 使用隔离的 tempfile.TemporaryDirectory() - 每次运行后都会删除
• 30 秒硬超时，并显式终止进程
• 使用精简、干净的环境 - 不向脚本传递凭据或敏感环境变量
• 阻止注入环境变量（PATH、LD_PRELOAD、PYTHONPATH 等）
• 永不向 Agent 返回脚本源码 - 仅返回 stdout / stderr / exit_code
• 每个输出流截断至 10,000 个字符

在已部署的 Cloudflare Worker 中，skills_run_script 仅返回脚本清单——Pyodide 运行时无法运行子进程。

---

项目结构

三个顶层目录分别负责三个不同的方面：

• skill_mcp/ - Python 包。服务在运行时所需的一切都在这里：Pydantic 模型（models/）、Qdrant 集成（db/）、MCP 工具实现（tools/）、提示词注入扫描器（security/）、种子脚本（seed/）、本地 FastMCP 入口点（server.py），以及技能注册表本身（skills_data/）。如果要添加技能、编辑工具或修改数据层，就在这里操作。

• src/ - Cloudflare Workers 部署目标。包含一个文件 worker.py，其中将六个 MCP 工具重新实现为独立的 Cloudflare Python Worker（无外部包，兼容 Pyodide）。仓库根目录中的 wrangler.jsonc 指向这里。仅在需要更改已部署 Worker 的行为时编辑此目录。

• scripts/ - 不属于可导入包的开发和 CI 工具。setup.sh / setup.ps1 是一次性交互式向导；validate_skills.py 是 SKILL.md 架构 + 提示词注入验证器，由 make validate 和 GitHub Actions 技能验证工作流调用。

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

---

已知限制

• 需要安装主技能文件才能确保 Agent 行为可靠 - 只有将主技能文件安装在 Agent 的项目根目录中，三级工作流（发现 → 加载 → 补充）才会稳定触发（参见上文步骤 2）。如果没有该文件，Agent 可能会跳过评分阈值，推测性地加载技能正文，或完全忽略 tier3_manifest，从而浪费上下文窗口 token，并导致结果不一致。

• Token 用量随集合规模增加 - skills_find_relevant 会返回 top_k 个结果描述（每个约 100–200 个 token）。有 30 个技能时，这点用量微不足道。有 300 个以上技能且 top_k 值较高时，单次发现调用就可能占用上下文窗口中相当一部分空间。请将 top_k 保持在较低水平（3–5），并为每项技能编写准确且彼此区别明显的触发短语，以便在规模扩大时维持相关性。

• 脚本只能在本地执行 - skills_run_script 需要本地 Python 服务端。Cloudflare Worker 会返回脚本清单，但无法执行子进程，因为 Pyodide 运行时不支持 subprocess。任何调用 skills_run_script 的技能工作流都必须将 MCP 客户端指向 python -m skill_mcp.server，而不是 Worker URL。

• 嵌入模型在种子数据生成时固定 - 种子数据生成和查询时都会使用 @cf/baai/bge-small-en-v1.5（384 维）生成向量。如果 Cloudflare Workers AI 停用或更改此模型，所有向量都将无法比较，整个技能集合都必须重新生成种子数据。

• 搜索质量取决于触发短语的质量 - 语义搜索的效果取决于每个 SKILL.md 中编写的 triggers。触发短语含糊或彼此重叠的技能会出现在不相关的查询结果中，降低结果相关性。一项技能的触发短语写得不好，就会影响整个注册表。

---

参与贡献

请阅读 CONTRIBUTING.md，了解完整的技能提交工作流，包括优秀技能的标准、SKILL.md 格式参考、分步 PR 流程，以及提交技能的安全策略。

快速开始：

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

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

# 3. Open a PR - CI runs automatically

绝不能违反的两条原则：

1. 绝不嵌入完整正文，只有 description + triggers 会写入向量集合
2. 绝不返回脚本源代码，skills_run_script 只返回 stdout / stderr / exit_code

CI 会验证每个涉及 skills_data/ 的 PR：检查 YAML 语法、架构、重复 slug，并扫描提示词注入。扫描失败会阻止合并。

---

许可证

Apache 2.0，参见 LICENSE。

---