Skill Swarm MCP

技能群

用于AI代理技能发现、安装和编排的MCP服务器。

   

______________________________________________________________________

问题

人工智能代理（克劳德、双子座、副驾驶）需要技能才能有效。如今，为任务查找和安装正确的MCP服务器是手动的：

1. 手动搜索Smithery/GitHub
2. 评估服务器是否值得信赖（星级？许可证？维护？）
3. 手动安装和配置
4. 对每个项目重复

Skill Swarm使整个流程自动化。 代理查询“pdf解析”，Skill Swarm搜索5个注册表（Skills.sh、MCP Registry、Smithery、Glama、GitHub），评估信任，安装最佳匹配，并立即提供。

______________________________________________________________________

运作原理

flowchart TD
    A["🤖 Agent queries:
'database access'"] --> B{match_skills}
    B -->|Local skill found| C["✅ Use it"]
    B -->|No match| D[search_skills]
    D --> E["5 registries
in parallel"]
    E --> F[install_skill]
    F --> G["download"]
    G --> H["security scan"]
    H --> I["trust check"]
    I --> J["install"]
    J --> K["symlink"]
    K --> L["~/.agent/skills/{name}/SKILL.md"]
    C --> M{Need partial context?}
    M -->|Yes| N[cherry_pick_context]
    M -->|No| O["📄 Full skill loaded"]
    N --> P["Extract only
sections you need"]

    style A fill:#8B5CF6,stroke:#6D28D9,color:#fff
    style C fill:#10B981,stroke:#059669,color:#fff
    style L fill:#10B981,stroke:#059669,color:#fff
    style F fill:#3B82F6,stroke:#2563EB,color:#fff
    style D fill:#3B82F6,stroke:#2563EB,color:#fff
    style N fill:#F59E0B,stroke:#D97706,color:#fff

搜索编排

远程搜索使用两阶段策略——首先是高信任注册表，只有在需要时才回退：

flowchart LR
    Q["Query"] --> P1["Phase 1
Skills.sh + MCP Registry"]
    P1 -->|">= 3 results"| D["Deduplicate
+ Trust Score"]
    P1 -->|" D
    D --> R["Sorted Results"]

    style Q fill:#8B5CF6,stroke:#6D28D9,color:#fff
    style P1 fill:#10B981,stroke:#059669,color:#fff
    style P2 fill:#F59E0B,stroke:#D97706,color:#fff
    style D fill:#3B82F6,stroke:#2563EB,color:#fff
    style R fill:#10B981,stroke:#059669,color:#fff

建筑

graph TB
    Agent["🤖 AI Agent (Claude, Gemini)"]
    Agent -->|MCP Protocol stdio| Server

    subgraph Server["skill-swarm MCP Server"]
        direction TB
        Tools["9 Tools · Python 3.13"]
        subgraph Core["Core Engines"]
            Matcher["Matcher V2
BM25F + 7 signals"]
            Trust["Trust Engine
5 dimensions · git-quality"]
        end
        subgraph Infra["Infrastructure"]
            Cache["Cache Layer
TTL file · 1h/24h"]
            Usage["Usage Tracker
dead skill detection"]
        end
    end

    Server --> Registries
    Server --> Skills

    subgraph Registries["5 Registries"]
        SkillsSH["Skills.sh"]
        MCP["MCP Registry"]
        Smithery["Smithery"]
        Glama["Glama.ai"]
        GitHub["GitHub (+token)"]
    end

    subgraph Skills["~/.agent/skills/"]
        SkillFile["{name}/SKILL.md"]
        Symlinks["Symlinked to:
~/.claude/skills/
~/.gemini/skills/"]
    end

    style Agent fill:#8B5CF6,stroke:#6D28D9,color:#fff
    style Server fill:#1E293B,stroke:#334155,color:#fff
    style Tools fill:#334155,stroke:#475569,color:#fff
    style Matcher fill:#3B82F6,stroke:#2563EB,color:#fff
    style Trust fill:#3B82F6,stroke:#2563EB,color:#fff
    style Cache fill:#475569,stroke:#64748B,color:#fff
    style Usage fill:#475569,stroke:#64748B,color:#fff
    style Skills fill:#10B981,stroke:#059669,color:#fff

安装管道

sequenceDiagram
    participant A as AI Agent
    participant S as skill-swarm
    participant R as Registries
    participant G as GitHub API
    participant FS as Filesystem

    A->>S: install_skill("pdf-parser", url)
    S->>S: Download source
    S->>S: Security scan (pattern matching)
    alt scan fails
        S-->>A: ❌ Blocked (security_score >G: GET /repos/{owner}/{repo}
    G-->>S: stars, license, pushed_at, archived
    S->>S: Compute trust score (5 dimensions)
    S->>FS: Write ~/.agent/skills/pdf-parser/SKILL.md
    S->>FS: Symlink ~/.claude/skills/pdf-parser → source
    S->>FS: Symlink ~/.gemini/skills/pdf-parser → source
    S->>S: Update manifest.json + usage tracker
    S->>S: Purge search cache
    S-->>A: ✅ InstallResult (path, agents, scores)

______________________________________________________________________

快速开始

先决条件

• Python 3.13+
• Git （用于克隆技能来源）
• GitHub代币 （可选，5000需求/小时对比60需求/小时）

安装

git clone https://github.com/ancrz/skill-swarm-mcp.git
cd skill-swarm-mcp

# Create virtual environment and install
python3.13 -m venv .venv
source .venv/bin/activate
pip install -e .

# Configure environment
cp .env.example .env
# Edit .env and add your GitHub token

配置您的AI代理

技能群使用 标准 传输——AI客户端启动Python进程，并通过stdin/stdout进行通信。这意味着客户端负责启动服务器并传递环境变量。

secrets如何与stdio协同工作： 因为客户端生成了流程 env JSON配置中的块在执行之前将变量注入服务器的内存。这是Claude和Gemini CLI的首选方法。对于沙盒代理（Antigravity），请使用 .env 文件（见下文）。

______________________________________________________________________

克劳德代码

Claude Code完全支持 type, command, args，以及 env 领域。

全球 (~/.claude.json):

{
  "mcpServers": {
    "skill-swarm": {
      "type": "stdio",
      "command": "/path/to/skill-swarm-mcp/.venv/bin/python",
      "args": ["-m", "skill_swarm.server"],
      "env": {
        "SKILL_SWARM_GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

项目级别 (.mcp.json 在项目根目录中）：

{
  "mcpServers": {
    "skill-swarm": {
      "command": "/path/to/skill-swarm-mcp/.venv/bin/python",
      "args": ["-m", "skill_swarm.server"],
      "env": {
        "SKILL_SWARM_GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

______________________________________________________________________

双子星命令行工具

Gemini CLI根据所使用的字段推断传输-- command = 标准。没有 type 场需要。这 env 砌块工程和支撑 $VAR / ${VAR} 从宿主环境中替换。

配置文件： ~/.gemini/settings.json

{
  "mcpServers": {
    "skill-swarm": {
      "command": "/path/to/skill-swarm-mcp/.venv/bin/python",
      "args": ["-m", "skill_swarm.server"],
      "env": {
        "SKILL_SWARM_GITHUB_TOKEN": "ghp_your_token_here"
      }
    }
  }
}

注： 省略 "type": "stdio" --Gemini CLI从以下内容推断出来 command。添加它可能会导致旧CLI版本上的验证错误。

______________________________________________________________________

反重力

反重力在一个 沙盒环境 （Docker或本地）。如果代理没有挂载您的主目录，Python二进制文件的绝对路径将失败。另外， env 在沙盒模式下，JSON的注入可能会受到限制。

推荐方法： 将GitHub令牌放入 .env skillsswarm目录中的文件，以便服务器从磁盘读取（Pydantic Settings加载 .env 自动）：

# /path/to/skill-swarm-mcp/.env
SKILL_SWARM_GITHUB_TOKEN=ghp_your_token_here

配置文件： ~/.gemini/antigravity/mcp_config.json

{
  "mcpServers": {
    "skill-swarm": {
      "command": "/path/to/skill-swarm-mcp/.venv/bin/python",
      "args": ["-m", "skill_swarm.server"]
    }
  }
}

注： 不 env block——服务器从其 .env 文件。确保可以从代理的执行上下文访问Python二进制文件的路径。

______________________________________________________________________

快速比较

验证

# Run tests
.venv/bin/python tests/test_core.py

# Test the MCP server responds
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"capabilities":{}}}' | \
  .venv/bin/python -m skill_swarm.server

______________________________________________________________________

9工具参考

看 TOOLS.md 完整的参数参考和示例。

______________________________________________________________________

技能目录合规性

技能遵循 .agent 跨代理兼容性标准：

~/.agent/skills/                    # Global source of truth
├── {skill-name}/
│   └── SKILL.md                    # Skill content (always SKILL.md)
├── manifest.json                   # Installed skills registry
├── .usage.json                     # Usage tracking data
└── .cache/                         # TTL-based search/trust cache

~/.claude/skills/                   # Agent-specific (symlinks)
├── {skill-name} -> ~/.agent/skills/{skill-name}
└── ...

~/.gemini/skills/                   # Agent-specific (symlinks)
├── {skill-name} -> ~/.agent/skills/{skill-name}
└── ...

• 这 文件夹名称 识别技能
• 这 文件 总是 SKILL.md （符合标准）
• 代理目录包含 目录符号链接 全球来源
• 任何遵循以下规则的代理人 .agent/skills/ 惯例会消耗技能

______________________________________________________________________

信任评分引擎

每个远程搜索结果都包含一个信任分数（0.0-1.0），该分数是根据5位数的质量维度计算得出的：

pie title Trust Score Weights
    "Maintenance" : 25
    "Security" : 25
    "Recency" : 20
    "Popularity" : 20
    "Completeness" : 10

判决：

stopword removal"] NQ --> Q["Keywords"] Q --> E["Exact Match w=30"] Q --> P["Prefix Match w=20"] Q --> PH["Phrase Match w=15"] Q --> B["BM25F w=15"] Q --> J["Jaccard Tags w=10"] Q --> FN["Fuzzy Name w=7"] Q --> FD["Fuzzy Desc w=3"]

E --> S["Σ Weighted Score 0.0 – 1.0"] P --> S PH --> S B --> S J --> S FN --> S FD --> S

style RQ fill:#F59E0B,stroke:#D97706,color:#fff style NQ fill:#F59E0B,stroke:#D97706,color:#fff style Q fill:#8B5CF6,stroke:#6D28D9,color:#fff style S fill:#10B981,stroke:#059669,color:#fff style E fill:#EF4444,stroke:#DC2626,color:#fff style P fill:#F97316,stroke:#EA580C,color:#fff style B fill:#3B82F6,stroke:#2563EB,color:#fff

|信号|重量|描述|
| ----------------- | ------ | ---------------------------------------------------- |
|完全匹配|30|查询等于技能名称|
|前缀匹配|20|技能名称以查询开头|
|短语匹配|15|查询在任何字段中都作为子字符串找到|
|BM25F|15|字段加权相关性（名称=3x，标签=2x，描述=1x）|
|Jaccard标签|10|设置标签的相似性|
|模糊名称|7|容忍拼写错误的名称匹配（rapidfuzz）|
|模糊描述|3|描述部分匹配|

针对小语料库（10-100个技能）优化的BM25F参数：k1=1.2，b=0.3。

______________________________________________________________________

## 平台支持

|平台|状态|注释|
| ----------- | ------------ | ------------------------------------- |
| **Linux** |全面支持|主开发平台|
| **macOS** |完全支持|相同的Python生态系统|
| **视窗** |完全支持|支持本机符号链接（见下文）|

### Windows符号链接

Skill Swarm使用目录符号链接(`os.symlink`)在代理商之间分享技能。Windows支持本机NTFS符号链接：

|Windows版本|要求|
| --------------------------------- | ------------------------------------------------------------------------ |
| **Windows 11** |无需配置——符号链接适用于所有用户|
| **Windows 10** （创作者更新+）|启用 **开发人员模式**：设置→ 更新和安全→ 对于开发者|
| **Windows 10** （旧版本）|以管理员身份运行|

Python的 `os.symlink()` 当满足上述权限时，它在Windows上本机工作。无需WSL。

**手动创建** （如果需要）：

PowerShell

New-Item -ItemType SymbolicLink -Path "$HOME\.claude\skills\my-skill" -Target "$HOME\.agent\skills\my-skill"

Command Prompt (Administrator)

mklink /D "%USERPROFILE%\.claude\skills\my-skill" "%USERPROFILE%\.agent\skills\my-skill"

**AI代理兼容性：**

|代理|集成| Symlink目录|
| ----------------- | ----------------------------- | ------------------- |
| **克劳德代码** | MCP stdio                     | `~/.claude/skills/` |
| **双子座** | MCP stdio                     | `~/.gemini/skills/` |
| **自定义代理** |添加到 `agent_dirs` in config |可配置|

______________________________________________________________________

## 配置参考

所有设置都是从环境变量加载的（前缀： `SKILL_SWARM_`):

|变量|默认值|描述|
| -------------------------------------- | --------- | -------------------------------------------- |
| `SKILL_SWARM_GITHUB_TOKEN` | _（空）_ |用于API访问的GitHub PAT（5000请求/小时）|
| `SKILL_SWARM_CACHE_SEARCH_TTL` | `3600` |搜索缓存TTL（秒）|
| `SKILL_SWARM_CACHE_TRUST_TTL` | `86400` |信任分数缓存TTL（秒）|
| `SKILL_SWARM_SEARCH_TIMEOUT` | `15.0` |注册表查询的HTTP超时|
| `SKILL_SWARM_SEARCH_MAX_RESULTS` | `10` |每次搜索的最大结果数|
| `SKILL_SWARM_SECURITY_THRESHOLD` | `0.5` |要安装的最低安全扫描分数|
| `SKILL_SWARM_SKILLSSH_ENABLED` | `true` |启用Skills.sh作为主注册表|
| `SKILL_SWARM_SKILLSSH_NPX_PATH` | `npx` |npx二进制文件的路径 `skills find` |
| `SKILL_SWARM_SKILLSSH_GITHUB_FALLBACK` | `true` |当npx不可用时使用GitHub主题搜索|
| `SKILL_SWARM_SKILLSSH_SEARCH_TIMEOUT` | `30.0` |npx子流程调用超时|
| `SKILL_SWARM_SEARCH_PHASE1_MIN_RESULTS` | `3` |第二阶段搜索触发阈值|

______________________________________________________________________

## 项目结构

skill-swarm/ ├── src/skill_swarm/ │ ├── server.py # FastMCP entry point (9 tools) │ ├── config.py # Pydantic Settings + path helpers │ ├── models.py # Data models (SkillInfo, TrustScore, etc.) │ ├── core/ │ │ ├── scanner.py # Security pattern scanner │ │ ├── normalizer.py # Query normalization (stopword removal) │ │ ├── matcher.py # BM25F + multi-signal scoring │ │ ├── installer.py # Download, scan, install pipeline │ │ ├── registry.py # 5-registry parallel search (Skills.sh primary) │ │ ├── trust.py # Git-quality trust scoring engine │ │ ├── cache.py # TTL file-based cache │ │ └── usage.py # Skill usage tracking │ └── tools/ │ ├── search.py # search_skills implementation │ ├── install.py # install/uninstall wiring │ ├── inventory.py # list/match/get_info wiring │ └── cherry_pick.py # Section extraction ├── agnos/ # Agnostic specs (paradigm bridge) │ ├── spec-orchestration.md │ ├── spec-task-dependencies.md │ └── spec-agent-dispatch.md ├── skill/ │ ├── SKILL.md # Self-describing skill file │ └── references/ # Skill reference docs ├── tests/ │ ├── test_core.py # Unit tests (8) │ ├── test_e2e_effectiveness.py # E2E V1 (19 tests) │ └── test_e2e_v2.py # E2E V2 — trust, cache, BM25F (15 tests) ├── LICENSE # Apache 2.0 ├── README.md # This file ├── TOOLS.md # Complete tool reference ├── pyproject.toml # Python package config ├── .env.example # Environment template ├── .mcp.json # MCP server config └── .gitignore

______________________________________________________________________

## 发展

Install with dev dependencies

pip install -e ".[dev]"

Run all non-network tests

.venv/bin/python -m pytest tests/ -v -m "not network"

Run with network tests (requires internet access)

.venv/bin/python -m pytest tests/ -v

Test a single search

.venv/bin/python -c " import asyncio, sys, json sys.path.insert(0, 'src') from skill_swarm.tools.search import search_skills results = asyncio.run(search_skills('filesystem', scope='remote', limit=3)) for r in results: trust = r.trust.score if r.trust else 'N/A' print(f'{r.name} ({r.source}) trust={trust}') "

______________________________________________________________________

## 许可证

Apache许可证2.0——请参阅 [许可证](LICENSE) 了解详情。

Copyright 2025 Anthony Cruz

**采用MCP协议和人工智能辅助工程构建。**

[⬆ 返回顶部](#skill-swarm)