Skill Swarm

MCP server for AI agent skill discovery, installation, and orchestration.

The Problem

AI agents (Claude, Gemini, Copilot) need skills to be effective. Today, finding and installing the right MCP server for a task is manual:

1. Search Smithery/GitHub manually
2. Evaluate if the server is trustworthy (stars? license? maintained?)
3. Install and configure it by hand
4. Repeat for every project

Skill Swarm automates the entire pipeline. The agent queries "pdf parsing" and Skill Swarm searches 5 registries (Skills.sh, MCP Registry, Smithery, Glama, GitHub), evaluates trust, installs the best match, and makes it available instantly.

How It Works

flowchart TD
    A["🤖 Agent queries:<br/>'database access'"] --> B{match_skills}
    B -->|Local skill found| C["✅ Use it"]
    B -->|No match| D[search_skills]
    D --> E["5 registries<br/>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<br/>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

Search Orchestration

Remote search uses a two-phase strategy — high-trust registries first, fallback only if needed:

flowchart LR
    Q["Query"] --> P1["Phase 1<br/>Skills.sh + MCP Registry"]
    P1 -->|">= 3 results"| D["Deduplicate<br/>+ Trust Score"]
    P1 -->|"< 3 results"| P2["Phase 2<br/>Smithery + Glama + GitHub"]
    P2 --> 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

Architecture

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<br/>BM25F + 7 signals"]
            Trust["Trust Engine<br/>5 dimensions · git-quality"]
        end
        subgraph Infra["Infrastructure"]
            Cache["Cache Layer<br/>TTL file · 1h/24h"]
            Usage["Usage Tracker<br/>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:<br/>~/.claude/skills/<br/>~/.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

Install Pipeline

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 < 0.5)
    end
    S->>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)

Quick Start

Prerequisites

• Python 3.13+
• Git (for cloning skill sources)
• GitHub token (optional, for 5000 req/hr vs 60)

Installation

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

Configure Your AI Agent

Skill Swarm uses stdio transport — the AI client launches the Python process and communicates via stdin/stdout. This means the client is responsible for starting the server and passing environment variables.

How secrets work with stdio: Because the client spawns the process, the env block in the JSON config injects variables into the server's memory before execution. This is the preferred method for Claude and Gemini CLI. For sandboxed agents (Antigravity), use a .env file instead (see below).

Claude Code

Claude Code fully supports type, command, args, and env fields.

Global (~/.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"
      }
    }
  }
}

Project-level (.mcp.json in your project root):

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

Gemini CLI infers transport from the field used — command = stdio. No type field needed. The env block works and supports $VAR / ${VAR} substitution from host environment.

Config file: ~/.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"
      }
    }
  }
}

Note: Omit "type": "stdio" — Gemini CLI infers it from command. Adding it may cause validation errors on older CLI versions.

Antigravity

Antigravity runs agents in a sandboxed environment (Docker or local). If the agent doesn't have your home directory mounted, absolute paths to the Python binary will fail. Additionally, env injection from the JSON may be restricted in sandboxed mode.

Recommended approach: Put the GitHub token in the .env file inside the skill-swarm directory so the server reads it from disk (Pydantic Settings loads .env automatically):

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

Config file: ~/.gemini/antigravity/mcp_config.json

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

Note: No env block — the server reads credentials from its .env file. Make sure the path to the Python binary is accessible from the agent's execution context.

Quick Comparison

Verify

# 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 Reference

See TOOLS.md for complete parameter reference and examples.

Skill Directory Compliance

Skills follow the .agent standard for cross-agent compatibility:

~/.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}
└── ...

• The folder name identifies the skill
• The file is always SKILL.md (standard compliance)
• Agent directories contain directory symlinks to the global source
• Any agent that follows the .agent/skills/ convention can consume skills

Trust Score Engine

Every remote search result includes a trust score (0.0-1.0) computed from 5 git-quality dimensions:

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

Verdicts:

Matcher V2 — BM25F + Multi-Signal Scoring

Local skill matching uses 7 weighted signals:

graph LR
    RQ["Raw Query"] --> NQ["Normalize<br/>stopword removal"]
    NQ --> Q["Keywords"]
    Q --> E["Exact Match<br/>w=30"]
    Q --> P["Prefix Match<br/>w=20"]
    Q --> PH["Phrase Match<br/>w=15"]
    Q --> B["BM25F<br/>w=15"]
    Q --> J["Jaccard Tags<br/>w=10"]
    Q --> FN["Fuzzy Name<br/>w=7"]
    Q --> FD["Fuzzy Desc<br/>w=3"]

    E --> S["Σ Weighted Score<br/>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

BM25F parameters optimized for small corpus (10-100 skills): k1=1.2, b=0.3.

Platform Support

Windows Symlinks

Skill Swarm uses directory symlinks (os.symlink) to share skills across agents. Windows supports native NTFS symlinks:

Python's os.symlink() works natively on Windows when the above permissions are met. No WSL required.

Manual creation (if needed):

# 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 Agent Compatibility:

Configuration Reference

All settings are loaded from environment variables (prefix: SKILL_SWARM_):

Project Structure

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

Development

# 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}')
"

License

Apache License 2.0 — see LICENSE for details.

Copyright 2025 Anthony Cruz

Built with MCP Protocol and AI-assisted engineering.

⬆ Back to Top