技能发现与安装MCP服务器

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["validate Agent Skills format"]
    J --> L["atomic folder install<br/>~/.agents/skills/{name}/"]
    L --> K["reconcile client discovery<br/>Claude · agy · Codex"]
    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

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<br/>+ GitHub (if token)"]
    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

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

    subgraph Server["skill-swarm MCP Server"]
        direction TB
        Tools["9 Tools · Python 3.12+"]
        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["Global Skill Discovery"]
        Canonical["~/.agents/skills/{name}/<br/>SKILL.md · scripts · references · assets"]
        ClaudeLinks["~/.claude/skills/{name}<br/>managed symlink"]
        AgyLinks["agy global skill paths<br/>managed symlinks"]
        CodexNative["Codex<br/>reads canonical source"]
        Canonical --> ClaudeLinks
        Canonical --> AgyLinks
        Canonical --> CodexNative
    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 Canonical fill:#10B981,stroke:#059669,color:#fff
    style ClaudeLinks fill:#E1F5EE,stroke:#0F6E56,color:#04342C
    style AgyLinks fill:#E1F5EE,stroke:#0F6E56,color:#04342C
    style CodexNative fill:#E1F5EE,stroke:#0F6E56,color:#04342C

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

    A->>S: install_skill("pdf-parser", url)
    S->>R: Fetch source (GitHub, npx, etc.)
    S->>S: Download complete skill folder
    S->>S: Security scan (pattern matching)
    alt scan fails
        S-->>A: ❌ Blocked (security_score < 0.5)
    end
    S->>S: Validate SKILL.md frontmatter
    S->>FS: Stage and atomically install complete folder
    S->>FS: Manage symlinks (~/.claude, ~/.gemini, ~/.agents)
    S->>S: Update manifest.json + usage tracker
    S->>S: Purge search cache
    S-->>A: ✅ InstallResult (path, agents, scores)

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

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

# Configure environment
cp .env.example .env

# Safely add your GitHub token without leaking it to shell history:
printf "Enter SKILL_SWARM_GITHUB_TOKEN (hidden): " && read -s val && echo && echo "SKILL_SWARM_GITHUB_TOKEN=$val" >> .env

claude mcp add --scope user skill-swarm \
  -e SKILL_SWARM_ENV_FILE="$HOME/.env" \
  -- "$PWD/.venv/bin/python" -m skill_swarm.server

agy mcp add --env SKILL_SWARM_ENV_FILE="$HOME/.env" \
  skill-swarm "$PWD/.venv/bin/python" -m skill_swarm.server

cat << 'EOF' >> ~/.codex/config.toml

[mcpServers.skill-swarm]
command = "python"
args = ["-m", "skill_swarm.server"]
env = { SKILL_SWARM_ENV_FILE = "~/.env" }
EOF

# Unit tests
.venv/bin/python -m pytest -q tests/test_core.py

# Confirm each global client sees the server
claude mcp list
agy mcp list
codex mcp list

~/.agents/skills/                   # Global source; Codex reads it directly
├── {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} -> ~/.agents/skills/{skill-name}
└── ...

~/.gemini/config/skills/            # agy current global path (symlinks)
├── {skill-name} -> ~/.agents/skills/{skill-name}
└── ...

~/.gemini/antigravity-cli/skills/  # agy migration compatibility
├── {skill-name} -> ~/.agents/skills/{skill-name}
└── ...

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

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

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

# Command Prompt (Administrator)
mklink /D "%USERPROFILE%\.claude\skills\my-skill" "%USERPROFILE%\.agents\skills\my-skill"

skill-swarm-mcp/
├── src/skill_swarm/
│   ├── server.py              # MCPServer 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 (25)
│   ├── test_e2e_effectiveness.py  # E2E V1 (19 tests)
│   └── test_e2e_v2.py         # E2E V2 — trust, cache, BM25F (19 tests)
├── LICENSE                    # Apache 2.0
├── README.md                  # This file
├── TOOLS.md                   # Complete tool reference
├── pyproject.toml             # Python package config
├── uv.lock                    # Reproducible dependency lock
├── .env.example               # Environment template
└── .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}')
"

Copyright 2025 Anthony Cruz