io.github.skill-federation/skillfed-mcp

Official

by skill-federation · Python

Find vetted agent skills for your task — privacy-preserving skill discovery over MCP.

Privacy-preserving discovery of vetted agent skills for specific tasks.

Topics

agent-skillsai-agentsclaude-codeclaude-skillsmcpskill-discoveryskill-searchskillsmpskill-federation

README.md14 KBView on GitHub

Skill Federation

Free, private skill search for AI agents

Your agent asks. Skill Federation answers. You approve.

A bare agent solves 17.5% of SkillsBench tasks. With Skill Federation, 22.8% — and your work never leaves your machine.

</div>

Your coding agent keeps rebuilding things that a packaged skill already does well — PDF extraction, market sizing, data cleaning, PR review, Slack notifications, SQL reporting. The skills exist, scattered across the open-source ecosystem. The problem is finding the right one mid-task — and every "search a catalog" approach so far means shipping your plan, your brief, or your data to someone's server.

Skill Federation finds skills the privacy-preserving way. Right after you approve a plan, your agent writes an abstract wish-list — "if every skill existed, which would I reach for?" — and the federation matches those wishes against a catalog of vetted skills. Your plan, your files, and your outputs never leave your machine. Only the abstract wishes do.

IMPORTANT

Only the abstract wish crosses the boundary — a one-line capability description, ~4 vocabulary-varied paraphrases, 1–5 keywords, and a capability-level sketch of the ideal skill. Every field is "what skill should exist," never your task. Your plan, brief, file contents, and reasoning trace stay local — always.

Here's the entire payload for one wish — the literal string sent for launch-strategy. It names the capability domain, never your task, plans, or product:

text

description: plan a multi-channel launch for an open-source developer tool
paraphrases: orchestrate a launch across hacker news reddit and product hunt · plan a
             go-to-market launch for a dev tool · coordinate a multi-platform release
             announcement · design a launch-day plan for an open-source project
sketch:      launch product hunt hacker news waitlist go-to-market campaign ·
             channel planning timing asset prep announcement
keywords:    launch, gtm, product-hunt, strategy, announcement

That's it — a description, four paraphrases, a capability sketch, and keywords. Your product's name, your unreleased roadmap, and your actual launch plan never appear.

<details> <summary>Prefer plain text? Here's the same run</summary>

code

You: /skillfed plan a launch for my open-source dev tool

  -> agent writes 4 abstract wishes (paraphrases + a capability sketch).
     Only these leave your machine -- never your plan, files, or data.

  wish: launch-strategy       -> multi-platform-launch  review - verified             <- selected
  wish: repo-discoverability  -> github-presence        review - verified             <- selected
  wish: community-building    -> community-building     review - verified             <- selected
  wish: growth-analytics      -> product-analytics      permissive - verified - 221*  <- selected
       (each picked from 5 ranked candidates in the vetted catalog)

  Install the 4 selected? They go in .claude/skills/ with license + source attribution.

</details>

🔒 Why it's different

Privacy floor, by design. Only the abstract wish crosses the boundary — "what skill should exist," never your task. Your plan, brief, file contents, and reasoning trace stay local, always. (Full field-by-field breakdown under Privacy & trust below.)
Trust before install. Candidates come from a pre-scanned internal registry (Cisco Skill Scanner + NVIDIA SkillSpector), not the wild repo — every one shows its license class, provenance, stars, and source. You approve each install; nothing is pulled silently. (See Security.)
Native, zero-install. The default tier needs nothing but curl — already on Windows 10+ and macOS. No Python, no Node, no package manager. (Optional tiers add typed MCP tools if you have Node.)

⚙️ How it works

Plan. You approve a plan in your agent as usual.
Wish-list. The agent sketches the ideal skills and writes up to 10 abstract wishes — each with vocabulary-varied paraphrases and a structured capability sketch for high recall. No task specifics.
Match. The federation runs a fast lexical search per wish (description + paraphrases + flattened sketch) against the vetted, pre-scanned catalog and returns the top candidates.
Review. The agent picks the best fit (or rejects all) and shows you a trust table.
Install. On your approval, the chosen skills are fetched from the internal scanned copy (not the origin repo) into .claude/skills/ with full license + source attribution.
Use. Your agent uses the skill immediately — no reinventing it.

📊 Benchmark

We measured Skill Federation on SkillsBench (coding-agent tasks with deterministic verifiers), with the agent harnessed as Claude Code (Opus 4.6). The catch that makes this a real test: the skill Skillfed retrieves comes from a 26,629-skill snapshot of the public catalog (which holds 87k+ skills overall) with the benchmark's own answer skills removed — so this measures whether independently authored skills transfer to the task, not whether we can re-find the benchmark's hand-written one.

Condition	What the agent gets	Success
No skill	bare Claude Code (Opus 4.6)	17.5%
Skillfed	top skill retrieved from the 26,629-skill snapshot	22.8%
Oracle	the task's own hand-written skill — an unreachable upper bound	36.8%

Skillfed lifts success from 17.5% to 22.8% — a ~30% relative gain over the bare agent, and recovers ~27% of the gap to an oracle skill it never sees. Most skill-retrieval results test oracle-recovery (the benchmark's own skill sits in the pool); this tests transfer — useful skills pulled from a large, noisy public catalog.

📦 Install

One line — no clone needed. You've already got Node or Python:

bash

# Node — npm
npx skillfed

bash

# Python — uv   (or:  pipx run skillfed)
uvx skillfed

Prefer Claude Code's plugin system? Add the marketplace and install the plugin:

text

/plugin marketplace add skill-federation/skill-federation
/plugin install skill-federation@skill-federation

No Node or Python? Ask Claude Code to install the curl version for you:

text

Install the Skill Federation /skillfed finder from github.com/skill-federation/skill-federation
— run its curl installer (install.ps1 on Windows, install.sh on macOS/Linux), then tell me to
restart Claude Code.

TIP

Then restart Claude Code and run /skillfed <what you're trying to do> — or just approve a plan and the finder offers itself automatically.

Zero runtime — the finder needs only curl (no Node or Python). For the optional tiers (auto-trigger hook · typed MCP tools · Python/CI helper), flags, scopes, installing from a checkout, and config-safety details, see install.md.

<details> <summary>Prefer to paste it yourself? (raw curl one-liner)</summary>

powershell

# Windows (PowerShell) — irm|iex also sidesteps the execution-policy block
irm https://raw.githubusercontent.com/skill-federation/skill-federation/main/install.ps1 | iex

bash

# macOS / Linux
curl -fsSL https://raw.githubusercontent.com/skill-federation/skill-federation/main/install.sh | bash

</details>

🛡️ Privacy & trust

NOTE

What never crosses: your plan, brief, file contents, outputs, or reasoning trace. What does: only the abstract wish (description + paraphrases + keywords + capability sketch).

<details> <summary>The full field-by-field breakdown</summary>

What crosses the boundary: the abstract wish — its one-line description, ~4 paraphrased formulations of it, 1–5 keywords, and a structured capability sketch of the ideal skill (purpose / inputs / outputs / operations / domain_vocab / section_sketch / tags). The sketch's flattened terms ride inside the search query on every search (they supply the discriminative vocabulary that drives recall); when no skill is found, that same sketch becomes the demand pointer — abstract enough to protect you, detailed enough to auto-build the missing skill. Every field is "what skill should exist", never your task. The wish's name is display-only and is not sent.
What never crosses: your plan, brief, file contents, outputs, or reasoning trace.
Two complementary signals, not conflated: a report_selection labels retrieval quality (which shown candidates were right or wrong); a report_demand captures the capability gap (what was actually needed). They feed different loops — selection sharpens search, demand drives what gets built next.
Local-first: if you already have a skill installed, your local copy is used as-is — your edits are personalization, never silently overwritten.

</details>

🔒 Security

Skill Federation treats every third-party skill as untrusted input. Skills are served from our internal, pre-scanned registry — never pulled live from the wild repo. At ingestion we copy each candidate, dedupe it, and scan it; only passing skills are promoted and served. The source link you see is provenance, not where the skill is fetched from.

Every candidate is best-effort scanned with two independent tools:

Cisco AI Defense Skill Scanner — YARA/pattern, bytecode, command-taint, behavioral dataflow, LLM-as-judge, and VirusTotal checks for prompt injection, data exfiltration, and malicious code.
NVIDIA SkillSpector — vulnerability-pattern + LLM analysis with live OSV.dev CVE lookups and a 0–100 risk score.

High/critical findings are rejected or routed to manual review before promotion — the wild catalog never reaches you unfiltered.

Why this matters. NVIDIA's study behind SkillSpector scanned 42,447 public skills and found 26.1% carried at least one vulnerability and 5.2% showed likely malicious intent — and an installed skill runs with your agent's full permissions. Serving straight from public repos would hand roughly one-in-four vulnerable and one-in-twenty malicious skills to your agent; the ingest gate is what keeps them out.

NOTE

Scanning is best-effort, not a guarantee. As Cisco's scanner puts it, "no findings ≠ no risk" — a clean scan is not proof a skill is safe. Skill Federation still shows each skill's license, provenance, and source, and nothing installs without your approval.

🔧 Configuration

The finder talks to a federation endpoint over HTTPS. Default is a keyless demo; override it:

bash

export SKILLFED_ENDPOINT="https://your-federation.example.com"   # or set in .mcp.json for the npx tier

📁 What's in this repo

code

install.ps1 / install.sh / install.md   auto-detecting installer; works from a clone OR piped (irm|iex, curl|bash)
installer/                              npm package `skillfed` — the `npx skillfed` no-clone path
python-installer/                       PyPI package `skillfed` — the `uvx skillfed` / `pipx run skillfed` path
scripts/vendor-payload.mjs              vendors the 3 payload files into both packages (single source of truth)
integrations/claude-code/               the Claude Code plugin (skill + /skillfed + hook) — canonical payload
integrations/*.py                       optional Python tier (advanced / CI)
mcp-server/                             optional Node MCP tier (typed tools via npx skillfed-mcp)

📄 License

Install

Configuration

Environment variables

SKILLFED_ENDPOINT

Hosted federation endpoint URL (defaults to the public demo Space if unset)

claude_desktop_config.json

{
  "mcpServers": {
    "skillfed-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "skillfed-mcp@0.1.3"
      ],
      "env": {
        "SKILLFED_ENDPOINT": "<YOUR_SKILLFED_ENDPOINT>"
      }
    }
  }
}