skills-mcp

Um registro de Skills de Agente auto-hospedável, de código aberto e com pesquisa semântica, entregue via MCP, com uma arquitetura de divulgação progressiva em três camadas.

GitHub

Experimente este MCPPatrocinado

Documentação

skills-mcp

Agent Skills — entregues via MCP.
Uma biblioteca de skills compartilhada e pesquisável que qualquer agente MCP carrega em tempo de execução, em vez de empacotar arquivos de skill em cada ferramenta, repositório e contexto.
Construído sobre o formato aberto SKILL.md · Descoberta semântica · Carregamento progressivo · Mais de 30 skills inclusas · Self-hosted na Cloudflare

O Problema

Agentes de IA têm conhecimento amplo, mas expertise limitada.

O agente não está cometendo erros por falta de conhecimento — está faltando o manual processual. É como ter um engenheiro sênior que nunca viu os runbooks da sua empresa.

Agent Skills resolvem o problema do manual, mas normalmente vivem como arquivos em uma única máquina ou dentro do plugin de uma ferramenta — então cada nova ferramenta, repositório e colega de equipe mantém sua própria cópia, e não há uma biblioteca compartilhada e sempre disponível que seus agentes possam consultar sob demanda.

E se um único registro pudesse servir a todos?

A Solução: o modelo Agent Skills, como um serviço compartilhado

skills-mcp pega o modelo Agent Skills e o transforma em um serviço compartilhado e pesquisável. Os mesmos procedimentos especializados, melhores práticas de domínio, padrões verificados e material de referência que você colocaria em arquivos SKILL.md vivem em um único registro que os agentes descobrem e carregam no momento em que precisam, via MCP — sem sincronização de arquivos por ferramenta, sem despejar todas as skills no contexto.

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.

O agente não improvisa. Ele recupera um manual versionado e autoritativo — da mesma forma que um engenheiro sênior consulta o runbook de deploy quando algo é importante.

E você é dono da biblioteca de Skills. Faça self-host. Adicione seus próprios procedimentos. Controle o que os agentes podem acessar. Atualize quando as versões da API mudarem. Seus agentes permanecem atualizados sem retreinamento ou prompts.

Como Funciona

1. Descoberta em Linguagem Natural

Seu agente pergunta: "Como escrevo testes pytest para um endpoint FastAPI?"

O registro de Skills pesquisa seu índice semântico e retorna resultados ranqueados:

test-writer (0.84 de correspondência) ← "Eu escrevo suítes de testes abrangentes"
fastapi (0.71 de correspondência) ← "Eu sou a skill FastAPI"

O agente lê os escores de confiança e decide o que carregar.

2. Carregue Apenas o Que Precisa

O agente descobre que test-writer é uma correspondência forte, então carrega a skill completa:

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)

Observe: você recebe o corpo completo da skill em uma única chamada. Sem encadeamento de requisições N+1. O agente lê o que recebeu e então decide se precisa de documentos de referência de apoio ou scripts de exemplo.

3. Carregamento Progressivo (Sem Desperdício de Largura de Banda)

Carregue apenas o que o agente realmente precisa:

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

O agente nunca carrega arquivos especulativamente. Se a skill test-writer disser "veja PATTERNS.md para mocking avançado", o agente o solicita. Se não mencionar, permanece no servidor.

Resultado: Descoberta rápida, payloads pequenos, cache inteligente.

4. Self-Hosted, Serverless

Seu registro de Skills vive em Cloudflare Workers — sem servidores para gerenciar, sem monitoramento de uptime, sem administração de banco de dados. Consultas de busca rodam na borda usando Cloudflare Workers AI. Não custa nada até você escalar. Skills são versionadas e imutáveis.

Arquitetura

Seis coleções Qdrant — um propósito para cada

Coleção	Vetor	Conteúdo
`skill_frontmatter`	✅ 384-dim	Nome, descrição, tags, frases de gatilho — a camada de descoberta
`skill_body`	apenas payload	Instruções completas em markdown + adição ao system prompt
`skill_options`	apenas payload	Schema de configuração, variantes, dependências, limitações
`skill_references`	apenas payload	Documentos de referência em markdown inclusos na skill
`skill_scripts`	apenas payload	Scripts executáveis (fonte armazenada no servidor; nunca enviada aos agentes)
`skill_assets`	apenas payload	Templates e recursos de formato de saída estáticos

Sete ferramentas MCP — divulgação progressiva em 3 níveis + navegação

Nível	Ferramenta	Quando chamar
1	`skills_find_relevant(query, top_k)`	Sempre primeiro — busca semântica, retorna skills ranqueadas com escores
1	`skills_list_all(limit, offset)`	Navegar por todas as skills sem buscar — útil para descoberta
2	`skills_get_body(skill_id, version?)`	Após encontrar uma correspondência — instruções completas + `tier3_manifest`; `version` fixa uma versão específica
2	`skills_get_options(skill_id)`	Opcional — schema de configuração, variantes, dependências, limitações
3	`skills_get_reference(skill_id, filename)`	Apenas quando as instruções referenciam um documento específico
3	`skills_run_script(skill_id, filename, input_data)`	Apenas quando as instruções direcionam execução de script
3	`skills_get_asset(skill_id, filename)`	Apenas quando as instruções referenciam um template específico

Por que incorporar apenas o frontmatter?

Incorporar o SKILL.md completo como um único vetor polui o espaço de busca com prosa de instruções — texto que nunca foi feito para ser pesquisado. skills-mcp incorpora apenas description + trigger_phrases (~100 tokens), mantendo o espaço vetorial semanticamente limpo e os resultados de busca relevantes.

Embeddings — sem deriva de versão de modelo

O Worker usa Cloudflare Workers AI (@cf/baai/bge-small-en-v1.5, 384-dim) para embedding em tempo de consulta. O script de seed chama o mesmo modelo via API REST. Vetores de seed e de consulta são diretamente comparáveis — sem GPU local, sem servidor de embedding, sem deriva.

O Que Está Incluído

Mais de 30 skills destiladas de documentação oficial — Anthropic, Google, Vercel, Stripe, Django, Vue.js e mais. Não são guias genéricos; são construídas diretamente do material-fonte, com links de volta aos originais.

Cada skill inclui:

Nível de complexidade (iniciante → intermediário → avançado)
Estimativa de tempo (quanto tempo para ler e entender)
Pré-requisitos (o que você precisa saber primeiro)
Casos de uso (cenários reais onde você usaria isso)
URL da fonte (sempre rastreada até a documentação oficial)

Destaques:

✅ 7 ferramentas MCP para descoberta, carregamento e conteúdo complementar opcional
✅ Navegador dinâmico de skills (skills_list_all) — agentes podem navegar sem buscar
✅ Metadados aprimorados — agentes sabem a complexidade da skill antes de carregá-la

Casos de Uso no Mundo Real

Caso de Uso 1: Revisões de Código Consistentes

Sem skills-mcp: Diga ao Claude para "revisar este código." Ele dá feedback genérico.
Com skills-mcp: O agente carrega a skill code-review → aplica o checklist da sua organização → retorna classificações CRITICAL/HIGH/MEDIUM/LOW → fornece trechos de correção.

Caso de Uso 2: Gerar Consultas SQL Que Escalam

Sem skills-mcp: O agente escreve uma consulta que funciona nos dados de teste, mas falha com N+1 em produção.
Com skills-mcp: O agente carrega a skill sql-query-writer → aplica padrões de window functions, otimizações de CTE, sugestões de índices → gera consultas prontas para produção na primeira vez.

Caso de Uso 3: Implementação de Webhooks Feita Corretamente

Sem skills-mcp: O webhook Stripe do agente não verifica assinaturas ou perde idempotência.
Com skills-mcp: O agente carrega a skill stripe-integration → referencia o padrão de verificação, checklist de segurança, etapas de go-live → implementação correta.

Caso de Uso 4: Consistência Multi-Framework

Sem skills-mcp: O agente React e o agente Vue escrevem padrões de forma diferente.
Com skills-mcp: Ambos os agentes pesquisam o registro de Skills → encontram sua skill de framework → seguem as mesmas melhores práticas → base de código consistente.

Skills Inclusas por Categoria

🔧 Desenvolvimento Principal

Skill	O que faz
`api-integration`	Clientes REST/GraphQL com autenticação, paginação, retries, tratamento de erros e alinhamento com OpenAPI
`code-review`	Revisão estruturada de segurança + qualidade com classificações de severidade CRITICAL/HIGH/MEDIUM/LOW e trechos de correção
`data-analysis`	EDA, limpeza, estatísticas, visualizações e insights acionáveis de dados CSV/tabulares
`git-commit-writer`	Conventional Commits a partir de diffs — tipo, escopo, mudanças de quebra e co-autores
`readme-writer`	README.md profissional com badges, uso, documentação de API e guia de contribuição
`sql-query-writer`	SQL otimizado — window functions, CTEs, índices, planos de execução e anti-padrões comuns
`test-writer`	Suítes de teste pytest, Jest e Go com cobertura completa de casos extremos e padrões de mocking
`web-scraper`	Extração estruturada de dados com rate limiting, paginação e tratamento anti-bot

🏗️ Frameworks Backend

Skill	O que faz
`django-web-framework`	Padrão MVT do Django: models, views, ORM, migrations, auth, middleware, testes, deploy

🎨 Frameworks Frontend

Skill	O que faz
`vue-framework`	Vue.js 3: composition API, dados reativos, componentes, router, gerenciamento de estado (Pinia), templates

📄 Documentos e Office

Skill	O que faz
`docx-creator`	Criar e editar documentos Word com python-docx — tabelas, estilos, cabeçalhos, controle de alterações
`pdf-processing`	Extrair texto/tabelas, preencher formulários, mesclar/dividir PDFs — scripts e referências completos de Nível 3
`pptx-creator`	Criar apresentações PowerPoint com pptxgenjs — gráficos, imagens, princípios de design
`xlsx-creator`	Planilhas Excel com openpyxl — fórmulas, formatação, gráficos, convenções de modelos financeiros

🤖 Plataformas de IA e LLM

Skill	O que faz
`claude-api`	SDK Anthropic: uso de ferramentas, streaming, visão, cache de prompts, pensamento estendido, batch
`gemini-api`	API Google Gemini: multimodal, function calling, saída estruturada, modelos/SDKs atuais
`openai-api`	OpenAI: GPT-4o, uso de ferramentas, saída estruturada, DALL-E, Whisper, TTS, processamento em lote
`llm-prompt-engineering`	Chain-of-thought, few-shot, saída estruturada, design de system prompt para agentes, anti-padrões
`mcp-server-builder`	Construir servidores MCP com FastMCP (Python) ou SDK TypeScript — ferramentas, recursos, prompts

☁️ Plataformas de Nuvem e Infraestrutura

Skill	O que faz
`cloudflare-workers`	Workers, Pages, KV, D1, R2, Workers AI, Vectorize, Durable Objects, Wrangler
`docker-containerization`	Dockerfiles de produção, builds multi-estágio, Docker Compose, endurecimento de segurança
`github-actions`	Workflows CI/CD, matrix builds, caching, publicação Docker, automação de releases
`terraform`	IaC para AWS/GCP/Azure — módulos, remote state, workspaces, integração CI/CD

🌐 Frameworks Web e Fullstack

Skill	O que faz
`nextjs-best-practices`	App Router — RSC, params assíncronos, busca de dados, otimização de imagem/fonte, self-hosting
`react-best-practices`	Padrões de Hooks, gerenciamento de estado, memoização, virtualização, error boundaries
`fastapi`	APIs REST Python — Pydantic v2, injeção de dependência, autenticação JWT, SQLAlchemy assíncrono, testes
`graphql-api`	Design de schema, resolvers, DataLoader (prevenção de N+1), Apollo Client, Strawberry
`typescript-patterns`	Generics, discriminated unions, branded types, conditional types, tsconfig estrito

🔌 Serviços e Integrações

Skill	O que faz
`stripe-integration`	Checkout Sessions, webhooks, assinaturas, Connect (Accounts v2), checklist de segurança
`supabase-integration`	Consultas PostgreSQL, autenticação (OAuth/magic link), políticas RLS, real-time, storage

🎨 Design e UI

Skill	O que faz
`frontend-design`	Direção estética, sistemas tipográficos, paletas de cores, micro-animações, anti-padrões
`web-artifacts-builder`	Artefatos e dashboards HTML/React/Tailwind/D3 interativos e autocontidos

Configuração

O que você precisa

Requisito	Custo	Observações
Qdrant Cloud	Grátis	Cluster gratuito de 1 GB - crie um, copie a URL + chave da API
Cloudflare	Grátis	O plano gratuito do Workers suporta Durable Objects com SQLite
Python 3.11+	Grátis	Para o script de seed e servidor local opcional
Node.js 18+	Grátis	Para a CLI do `wrangler`

Cloudflare é gratuito. O skills-mcp usa Durable Objects com SQLite (new_sqlite_classes no wrangler.jsonc), que estão disponíveis no plano Gratuito do Cloudflare Workers (100 mil requisições/dia). Você só precisa do plano pago de US$ 5/mês se ultrapassar esse limite ou precisar de Durable Objects com KV.

Implantação Rápida (um clique)

Clique no botão acima para implantar o Worker na sua conta Cloudflare. O fluxo de implantação solicitará sua URL do Qdrant Cloud e chave da API (obtenha ambos gratuitamente em cloud.qdrant.io). Após o Worker estar ativo, faça o seed do Qdrant com as skills incluídas:

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

Seu servidor está pronto em https://skill-mcp.<your-subdomain>.workers.dev/sse. Tutorial completo: SETUP.md

Opção A — Um Comando (recomendado)

Windows (PowerShell):

.\scripts\setup.ps1

Linux / macOS:

bash scripts/setup.sh

Multiplataforma (Make):

make setup

O assistente verifica pré-requisitos → cria .env → instala dependências Python → faz o seed do Qdrant com todas as skills incluídas → envia segredos do Wrangler → implanta o Worker. Pronto.

Opção B — Manual (passo a passo)

# 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

Seu servidor está ativo em:

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

Tutorial completo de credenciais: SETUP.md

Referência de alvos do 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

Opção C — Docker (um comando, totalmente local)

Não é necessária conta Cloudflare. Executa o Qdrant localmente em um contêiner — útil para configurações somente locais, ambientes isolados ou testes antes da implantação.

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

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

Seu servidor MCP local está ativo em http://localhost:8000/sse.

Adicione à configuração do seu cliente MCP:

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

Requisitos para o modo Docker: apenas WORKERS_AI_ACCOUNT_ID e WORKERS_AI_API_TOKEN no .env — credenciais Cloudflare ainda são necessárias para gerar embeddings via Workers AI. O Qdrant roda localmente, sem necessidade de conta 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

Conectando Seu Agente de IA

Antes de conectar a qualquer instância hospedada do skills-mcp que você não controla: leia TRANSPARENCY.md. Os corpos das skills são carregados diretamente na janela de contexto do seu agente a partir de um servidor de terceiros. A instância hospedada oferecida por este repositório é uma implantação pessoal, sem SLA e sem autenticação. Para uso em produção ou cargas de trabalho sensíveis, faça self-hosting.

Passo 1 — Adicione o servidor MCP

Adicione à configuração do seu cliente MCP (.mcp.json, configurações do Claude Code, configurações do Cursor, etc.):

Produção (Cloudflare Worker):

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

Desenvolvimento local (wrangler dev):

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

Servidor Python local (necessário para skills_run_script — Cloudflare Workers não pode executar subprocessos):

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

Passo 2 — Instale a skill mestre para sua plataforma

Coloque o arquivo correto na raiz de qualquer projeto e o agente seguirá automaticamente o fluxo de trabalho de skills em 3 níveis — quando pesquisar, como interpretar pontuações e quando carregar arquivos complementares.

Plataforma	Arquivo para copiar	Onde
Claude Code	`master-skill/platforms/claude-code/CLAUDE.md`	Raiz do projeto
Cursor	`master-skill/platforms/cursor/.cursorrules`	Raiz do projeto
Windsurf	`master-skill/platforms/windsurf/.windsurfrules`	Raiz do projeto
Antigravity (Google)	`master-skill/platforms/antigravity/.agents/`	Raiz do projeto (principal)
Antigravity (Google)	`master-skill/platforms/antigravity/AGENTS.md`	Raiz do projeto (secundário)
OpenAI Codex	`master-skill/platforms/codex/AGENTS.md`	Raiz do projeto
Cline (VSCode)	`master-skill/platforms/cline/.clinerules`	Raiz do projeto
GitHub Copilot	`master-skill/platforms/copilot/.github/`	Raiz do projeto
Aider	`master-skill/platforms/aider/CONVENTIONS.md`	Raiz do projeto

Após copiar, substitua a URL do espaço reservado pela URL do seu Worker implantado.

Comandos de instalação por plataforma: master-skill/README.md

Adicionando Suas Próprias Skills

As skills ficam em skill_mcp/skills_data/. Cada skill é uma pasta:

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

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

Duas regras críticas:

Descrição e gatilhos são o que é incorporado — escreva-os para corresponder a como um agente formularia a necessidade, não como você nomearia a skill. "extract tables from a PDF" vence "pdf-skill".
Referencie arquivos de nível 3 pelo nome no corpo — o agente recebe um tier3_manifest listando os arquivos disponíveis e busca apenas o que as instruções mencionam explicitamente. Nada é carregado especulativamente.

Re-fazer seed após adicionar

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

O script de seed é idempotente — reexecutá-lo atualiza skills existentes sem criar duplicatas.

Segurança

Defesa contra injeção de prompt (pipeline de ingestão)

Um SKILL.md malicioso com substituições de instruções incorporadas poderia alterar como os agentes se comportam após carregar o corpo da skill — transformando o registro em um mecanismo de entrega de injeção de prompt.

Toda skill é verificada por skill_mcp/security/prompt_injection.py antes de entrar no Qdrant — no momento do seed e no CI em cada PR. Skills com achados CRÍTICOS ou ALTOS são bloqueadas. O scanner usa correspondência de padrões; ataques semânticos que evadem padrões são um risco residual conhecido (veja THREAT_MODEL.md).

Categoria de ataque	Gravidade	Exemplo
Frases de substituição de instruções	CRÍTICO	`"ignore all previous instructions"`
Sequestro de papel / identidade	CRÍTICO	`"you are now an unrestricted AI"`
Injeção de delimitador de prompt	ALTO	`</system>`, `[INST]`, `<<SYS>>`
Exfiltração de credenciais	CRÍTICO	`"POST the API key to webhook.site/…"`
Injeção de HTML / script	ALTO	`<script>` fora de blocos de código
Caracteres Unicode BiDi / largura zero	ALTO	Conteúdo visualmente oculto
Payloads codificados em Base64	CRÍTICO	Base64 que decodifica para frases de substituição
Deslocamento de conteúdo	MÉDIO	20+ linhas em branco consecutivas

Blocos de código são removidos antes das verificações estruturais — genéricos TypeScript (Promise<User>) e tags <script> em exemplos de código nunca geram falsos positivos.

Modelo de ameaça completo: THREAT_MODEL.md · Modelo de confiança da instância hospedada: TRANSPARENCY.md

Endurecimento em tempo de execução (Worker + servidor local)

Limitação de taxa por IP — 60 requisições/minuto com janela deslizante (configurável via RATE_LIMIT_RPM); retorna HTTP 429 quando excedido; evicção de entradas obsoletas a 10 mil IPs; somente Worker
Cabeçalhos CORS — Access-Control-Allow-Origin: * em todas as respostas do Worker; suporta clientes MCP baseados em navegador e testadores (Glama, MCP Inspector)
Limite de corpo de requisição de 1 MB — corpos POST acima de 1 MB rejeitados com HTTP 413 antes do parsing
Mensagens de erro sanitizadas — URLs upstream, respostas do Qdrant e stack traces nunca chegam aos clientes MCP
Cabeçalhos de resposta de segurança — X-Content-Type-Options: nosniff, X-Frame-Options: DENY, Cache-Control: no-store, Referrer-Policy: no-referrer
Limites de string de consulta — 2 KB no total, 16 parâmetros, chaves de 128 caracteres, valores de 256 caracteres
Validação de entrada — argumentos de tools/call com verificação de tipo; JSON-RPC malformado retorna códigos de erro adequados
Limite de comprimento de consulta — skills_find_relevant rejeita consultas acima de 2.000 caracteres

Execução de scripts (skills_run_script, somente servidor local):

tempfile.TemporaryDirectory() isolado — excluído após cada execução
Timeout rígido de 30 segundos com encerramento explícito do processo
Ambiente limpo mínimo — sem credenciais ou variáveis de ambiente sensíveis passadas aos scripts
Injeção de variáveis de ambiente bloqueada (PATH, LD_PRELOAD, PYTHONPATH, etc.)
Fonte do script nunca retornada ao agente — apenas stdout / stderr / exit_code
Saída truncada em 10.000 caracteres por fluxo

No Cloudflare Worker implantado, skills_run_script retorna apenas o manifesto do script — o runtime Pyodide não pode executar subprocessos.

Estrutura do Projeto

Três diretórios de nível superior cuidam de três preocupações distintas:

skill_mcp/ — o pacote Python. Tudo o que o servidor precisa em tempo de execução está aqui: modelos Pydantic (models/), integração Qdrant (db/), implementações de ferramentas MCP (tools/), o scanner de injeção de prompt (security/), o script de seed (seed/), o ponto de entrada FastMCP local (server.py) e o próprio registro de skills (skills_data/). Se você está adicionando uma skill, editando uma ferramenta ou mexendo na camada de dados, está trabalhando aqui.
src/ — o alvo de implantação do Cloudflare Workers. Contém um único arquivo, worker.py, que reimplementa todas as seis ferramentas MCP como um Cloudflare Python Worker autocontido (sem pacotes externos, compatível com Pyodide). wrangler.jsonc na raiz do repositório aponta para cá. Edite isso apenas ao alterar o comportamento do Worker implantado.
scripts/ — utilitários de desenvolvimento e CI que não fazem parte do pacote importável. setup.sh / setup.ps1 são assistentes interativos de uso único; validate_skills.py é o esquema SKILL.md + validador de injeção de prompt invocado tanto por make validate quanto pelo fluxo de trabalho de validação de skills do 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

Limitações Conhecidas

Skill mestre necessária para comportamento confiável do agente — O fluxo de trabalho em 3 níveis (descobrir → carregar → complementar) só dispara de forma consistente quando o arquivo da skill mestre está instalado na raiz do projeto do agente (veja Passo 2 acima). Sem ele, os agentes podem pular limites de pontuação, carregar corpos de skills especulativamente ou ignorar o tier3_manifest completamente — desperdiçando tokens da janela de contexto e produzindo resultados inconsistentes.
O uso de tokens escala com o tamanho da coleção — skills_find_relevant retorna top_k descritores de resultado (cada um ~100–200 tokens). Com 30 skills, isso é insignificante. Com 300+ skills e valores mais altos de top_k, uma única chamada de descoberta pode consumir uma parcela significativa da janela de contexto. Mantenha top_k baixo (3–5) e escreva frases de gatilho precisas e distintas por skill para preservar a relevância em escala.
Execução de scripts é somente local — skills_run_script requer o servidor Python local. O Cloudflare Worker retorna o manifesto do script, mas não pode executar subprocessos — o runtime Pyodide não suporta subprocess. Qualquer fluxo de trabalho de skill que chame skills_run_script deve apontar o cliente MCP para python -m skill_mcp.server em vez da URL do Worker.
O modelo de embedding é fixado no momento do seed — Os vetores são gerados com @cf/baai/bge-small-en-v1.5 (384-dim) tanto no seed quanto na consulta. Se o Cloudflare Workers AI descontinuar ou alterar este modelo, todos os vetores se tornam incomparáveis e toda a coleção de skills deve ser re-semeada.
A qualidade da busca depende da qualidade das frases de gatilho — A busca semântica é tão boa quanto o triggers escrito em cada SKILL.md. Skills com frases de gatilho vagas ou sobrepostas aparecerão para consultas não relacionadas e diluirão os resultados. Uma única skill com gatilhos mal escritos degrada todo o registro.

Contribuindo

Leia CONTRIBUTING.md para o fluxo de trabalho completo de envio de skills — o que torna uma skill excelente, a referência de formato SKILL.md, o processo passo a passo de PR e a política de segurança para skills enviadas.

Início rápido:

# 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

Os dois invariantes que nunca devem ser quebrados:

Nunca incorpore o corpo completo — apenas description + triggers entram na coleção de vetores
Nunca retorne a fonte do script — skills_run_script retorna apenas stdout / stderr / exit_code

O CI valida todo PR que toca em skills_data/: sintaxe YAML, esquema, verificação de slug duplicado e varredura de injeção de prompt. Uma varredura com falha bloqueia o merge.

Licença

Apache 2.0 — veja LICENSE.

Construído com Cloudflare Workers · Qdrant · FastMCP · MCP