{ "markdown": "
\n\n# Skill Federation\n\n### Free, private skill search for AI agents\n\n\n[![Installs](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/skill-federation/skill-federation/badges/installs.json&label=installs&logo=serverless&logoColor=white&style=for-the-badge&cacheSeconds=300)](https://pypistats.org/packages/skillfed)\n[![Clones](https://img.shields.io/endpoint?url=https://raw.githubusercontent.com/skill-federation/skill-federation/badges/clones.json&label=clones&logo=github&logoColor=white&style=for-the-badge&cacheSeconds=300)](https://github.com/skill-federation/skill-federation)\n[![Stars](https://img.shields.io/github/stars/skill-federation/skill-federation?style=for-the-badge&color=E8C24A&logo=github&logoColor=white&cacheSeconds=1800)](https://github.com/skill-federation/skill-federation/stargazers)\n[![SkillsBench](https://img.shields.io/badge/SkillsBench-%2B30%25%20vs%20bare%20agent-E07A55?style=for-the-badge)](#-benchmark)\n\n\n[![npm](https://img.shields.io/npm/v/skillfed?logo=npm&logoColor=white&color=CB3837&label=npx%20skillfed&style=flat-square)](https://www.npmjs.com/package/skillfed)\n[![PyPI](https://img.shields.io/pypi/v/skillfed?logo=pypi&logoColor=white&color=3775A9&label=uvx%20skillfed&style=flat-square)](https://pypi.org/project/skillfed/)\n![Platform](https://img.shields.io/badge/platform-Windows%20%7C%20macOS%20%7C%20Linux-8A8377?style=flat-square)\n![Runtime](https://img.shields.io/badge/runtime-none%20(curl)-2E9E6B?style=flat-square)\n\n\n[![License](https://img.shields.io/github/license/skill-federation/skill-federation?color=7C5CDB&style=flat-square)](LICENSE)\n![Data sent](https://img.shields.io/badge/data%20sent-abstract%20wishes%20only-7C5CDB?style=flat-square)\n[![Agent Skill](https://img.shields.io/badge/Agent%20Skill-spec--conformant-2E9E6B?style=flat-square)](https://agentskills.io)\n\n\"Running\n\n**Skills are hints, not installs.** Your agent reads them as field notes; you approve the rare one worth keeping.\n\n*A bare agent solves 17.5% of SkillsBench tasks. With Skill Federation, 22.8% — and your work never leaves your machine.*\n\n**Browse and search the indexed catalogs — skills, PyPI packages, research — on the web → [skillfed.io](https://skillfed.io)**\n\n
\n\n---\n\nA model's weights are an **average** of what was written before its training cutoff, and a lossy\none at that. Wherever practice actually moves — SEO, security review, accessibility, framework and\nAPI migrations, packaging and release, pricing, compliance, tooling defaults — that average is a\nconfident summary of a *past* consensus. It reads exactly like expertise. It is also, quietly, a\nversion or two behind.\n\n**A skill is not a script you install. It's a hint.** Field notes a practitioner wrote down about\nhow this work is *currently* done: a dated artifact someone maintains, carrying the difference\nbetween the average and the present. A frontier model pulls one into context and augments its\nweights with it. Nothing else happens. So the normal outcome of a search here is **reading**, not\ninstalling; a skill is reference material, not code that runs.\n\n**Skill Federation finds those notes without telling anyone what you're working on.** When the work\nturns on how something is done *now*, your agent writes an abstract **wish-list** (\"if every skill\nexisted, which would I reach for?\") and the federation matches those wishes against a catalog of\nvetted skills. Your plan, your files, and your outputs never leave your machine. Only the abstract\nwishes do.\n\n**Read several, cross-check, install rarely.** In our own testing, skills read against work a\ncapable model had already optimised still surfaced real defects it had missed — *and* some of the\nskills' own advice was itself out of date. Both findings point the same way: pull several, compare\nthem, treat none as authoritative. Two independently authored skills agreeing is current practice;\none asserting alone is a hypothesis to verify. Stale skills argue for reading more than one. They\ndo not argue for trusting none.\n\n**You and your agent stay in command.** A skill is an input to judgment, never a replacement for\nit: take what's current and relevant, discard what doesn't fit, say which parts you used. And a\nfetched body is *data*, not instructions addressed to your agent. Craft guidance is what you came\nfor; anything telling the agent to run commands, change settings, or send data somewhere is\nignored and reported to you. (The catalog and our ongoing research notes are at\n[skillfed.io](https://skillfed.io).)\n\n> [!IMPORTANT]\n> **Only the abstract wish crosses the boundary** — a one-line capability description, ~4\n> vocabulary-varied paraphrases, 1–5 keywords, and a capability-level *sketch* of the ideal\n> skill. Every field is \"what skill should exist,\" never your task. Your plan, brief, file\n> contents, and reasoning trace stay local — **always**.\n\n**Here's the entire payload for one wish** — the literal string sent for `launch-strategy`.\nIt names the *capability domain*, never your task, plans, or product:\n\n```text\ndescription: plan a multi-channel launch for an open-source developer tool\nparaphrases: orchestrate a launch across hacker news reddit and product hunt · plan a\n go-to-market launch for a dev tool · coordinate a multi-platform release\n announcement · design a launch-day plan for an open-source project\nsketch: launch product hunt hacker news waitlist go-to-market campaign ·\n channel planning timing asset prep announcement\nkeywords: launch, gtm, product-hunt, strategy, announcement\n```\n\nA description, four paraphrases, a capability sketch, keywords. Your product's name, your\nunreleased roadmap, and your actual launch plan never appear.\n\n
\nPrefer plain text? Here's the same run\n\n```\nYou: /skillfed plan a launch for my open-source dev tool\n\n -> agent writes 4 abstract wishes (paraphrases + a capability sketch).\n Only these leave your machine -- never your plan, files, or data.\n\n wish: launch-strategy -> multi-platform-launch review - verified <- read\n wish: repo-discoverability -> github-presence review - verified <- read\n wish: community-building -> community-building review - verified <- read\n wish: growth-analytics -> product-analytics permissive - verified - 221* <- read\n (each picked from 10 ranked candidates in the vetted catalog)\n\n Read all 4 in context -- nothing hits disk. Install only the 1 you'll reuse?\n It goes in .claude/skills/ with license + source attribution.\n```\n\n
\n\n## 🔒 Why it's different\n\n- **Reading is the product; installing is the exception.** Skills are hints pulled into context,\n not packages fetched onto disk. The default flow ends after your agent has read several and told\n you what it took from each: nothing written, nothing to clean up. Installing happens only when a\n skill is good *and* you'll reuse it, and only with your approval.\n- **No harness required — not even Claude Code.** The finder skill carries its own triggers and its\n own instructions, so it works with no hook registered, in any harness that can load a skill body,\n and with **no harness at all** — paste it into a plain chat and it still knows when to search and\n how to read what it finds. (See **Works anywhere** below.)\n- **Privacy floor, by design.** Only the abstract wish crosses the boundary: \"what skill should\n exist,\" never your task. Your plan, brief, file contents, and reasoning trace stay local,\n always. (Full field-by-field breakdown under **Privacy & trust** below.)\n- **Trust before you read — and again before you install.** Candidates come from a **pre-scanned\n internal registry** ([Cisco Skill Scanner](https://github.com/cisco-ai-defense/skill-scanner) +\n [NVIDIA SkillSpector](https://github.com/NVIDIA/SkillSpector)), not the wild repo. Every one\n shows its license class, provenance, stars, and source. That matters twice over: a *consulted*\n body is untrusted third-party text entering your agent's context, and unlike an installed skill\n it leaves no `SOURCE.txt` behind, so the agent has to name what it read and where it came from\n in its reply. *You* approve each install; nothing is written to disk silently.\n (See [Security](#-security).)\n- **Native, zero-install.** The default tier needs nothing but `curl`, already on Windows 10+\n and macOS. No Python, no Node, no package manager. (Optional tiers add typed MCP tools if you\n have Node — including capability search over the PyPI package index and the research-notes\n index; see **Beyond skills** below.)\n\n## 🌍 Works anywhere\n\n**The finder is harness-agnostic on purpose.** Its triggers and its whole procedure live in the\nskill body. Register no hook, drop it into any harness that can load a skill body, or use no\nharness at all — it behaves the same. The optional Claude Code hooks below only *repeat* triggers\nthe skill already carries; **`--hook none` is the default**, and a complete install.\n\n**Nothing installed, just a browser?** Ask any chat to *use skillfed.io to find a skill* — or paste\nin [the skill body itself](integrations/claude-code/skills/skill-federation/SKILL.md), which carries\nthe whole procedure. The zero-install loop is two GETs — search, then read:\n\n- **Search** — [`skillfed.io/api/q/`](https://skillfed.io/api/q/pdf-extraction) returns\n ranked candidates for a query as one GET, each carrying a direct body URL plus trust fields.\n The terms ride in the *path* on purpose: chat fetchers routinely strip long query strings, so\n this form survives where `?q=` doesn't.\n- **Find** — the catalog is published as machine-readable JSON, no crawling required:\n [`skillfed.io/.well-known/agent-skills/index.json`](https://skillfed.io/.well-known/agent-skills/index.json)\n is one GET returning the whole index, each entry a skill name plus a direct `.md` URL;\n [`skillfed.io/api/index.json`](https://skillfed.io/api/index.json) is the fuller listing —\n publisher and license for every skill, 500 per page, follow `next`. (Hand these URLs to a chat\n directly; search-index coverage of the site is still shallow, so a thin web-search result can\n masquerade as a thin catalog.)\n- **Read** — append `.md` to any skill page URL for the full body as plain text. One GET, and you\n have it.\n\nWhat a browsing-only chat still can't run is the full wish-list protocol — several wishes at\nonce, each with paraphrases and a capability sketch, POSTed as one federated query. That's what\nthe finder tiers add.\n\n## 🧭 Beyond skills: packages & research\n\nskillfed.io indexes more than skills, and the MCP tier (`--with-npx`) exposes all three streams\nas typed tools:\n\n- **`find_skills`** — the vetted skill catalog everything above describes.\n- **`find_packages`** — capability search over the PyPI package index. About to `pip install`\n whatever name the model recalled from its weights? Describe the capability instead and get back\n real, current packages — each with a what-it-does card, license treatment, and a\n worth-installing verdict.\n- **`find_research`** — topic search over the research-notes index on the agent-skills\n literature: measured claims with sources, for when you want the evidence rather than a tool.\n\nThe two extra indexes are plain GETs (`/api/packages/search.json?q=…`,\n`/api/research/search.json?q=…`) — no auth, no tenant — so `curl` or any agent with a fetch tool\ncan use them without the MCP tier.\n\n## ⚙️ How it works\n\n
\n \"On\n
\n\n1. **Ask.** The skill's own triggers, which need no hook: as the agent *starts* planning (so skills\n shape the approach), when it *finishes* a plan, mid-task the instant it hits a capability it was\n about to build from scratch, or on request — `/skillfed `. It's a search, not\n a ritual: once or several times per task, as the work turns.\n2. **Wish-list.** The agent sketches the ideal skills and writes up to 10 abstract wishes — each\n with vocabulary-varied paraphrases and a structured capability sketch for high recall. No task\n specifics.\n3. **Match.** The federation runs a fast lexical search per wish (description + paraphrases +\n flattened sketch) against the **vetted, pre-scanned catalog** and returns the top candidates\n (10 per wish by default, 1–25 on request).\n4. **Read — the default.** The agent pulls **several** promising candidates per wish, reads them\n in context as field notes, and cross-checks where they disagree. Nothing is written to disk.\n You get a trust table (license · provenance · stars · source) plus a plain statement of which\n skills it read and what it took from each. **For most tasks it ends here.**\n5. **Install — the exception.** The skill has to be good *and* one you expect to reuse, and you\n have to approve it explicitly. Then it's fetched from the **internal scanned copy** (not the\n origin repo) into `.claude/skills/` with full license + source attribution. Nothing you only\n needed to read once gets installed.\n\n## 📊 Benchmark\n\n
\n\n\"SkillsBench\n\n
\n\nWe measured Skill Federation on **SkillsBench** (coding-agent tasks with deterministic verifiers),\nwith the agent harnessed as **Claude Code (Opus 4.6)**. What makes this a real test is the pool:\nthe skill Skillfed retrieves comes from a **26,629-skill snapshot of the public catalog** **with\nthe benchmark's own answer skills removed**. What that measures is whether *independently authored*\nskills transfer to the task, not whether we can re-find the benchmark's hand-written one.\n\n| Condition | What the agent gets | Success |\n|---|---|---|\n| No skill | bare Claude Code (Opus 4.6) | 17.5% |\n| **Skillfed** | top skill retrieved from the 26,629-skill snapshot | **22.8%** |\n| Oracle | the task's own hand-written skill — an unreachable upper bound | 36.8% |\n\nSkillfed lifts success **from 17.5% to 22.8% — a ~30% relative gain** over the bare agent, and\nrecovers **~27% of the gap** to an oracle skill it never sees. Most skill-retrieval results test\n*oracle-recovery* (the benchmark's own skill sits in the pool); this tests *transfer* — useful\nskills pulled from a large, noisy public catalog.\n\n> [!NOTE]\n> **How big is \"the public catalog\"?** Our own full census of the public SKILL.md corpus finds\n> **60,611 unique skills** across 6,177 repositories. Larger figures in circulation (~87k) count\n> the **86,956 vendored copies** sitting inside 64 aggregator repos — more copies than originals,\n> which turns every ecosystem statistic into a statistic about duplication. Details:\n> [60,611 skills in the wild](https://skillfed.io/research/reports/skills-in-the-wild-census).\n\n## 📦 Install\n\n**One line — no clone needed.** You've already got Node or Python:\n\n```bash\n# Node — npm\nnpx skillfed\n```\n```bash\n# Python — uv (or: pipx run skillfed)\nuvx skillfed\n```\n\n**Install one published skill** by the slug shown on its skillfed.io page:\n\n```bash\nnpx skillfed install owner/repository/skill\n```\n\nThe `install` subcommand ships with 0.2.1 and is npx-only — the shell, PowerShell, and Python\ninstallers don't have it. It checks the record\ncarries a usable license label and refuses unlicensed records by default, validates file\nboundaries and sizes, and verifies every SHA-256 — checksums are pinned by the skill's\npublished record — before writing to `.claude/skills/`; downloaded content is never executed.\nThe record's license and security-scan verdict are printed before any file is written, and a\n`fail` verdict refuses to install unless you pass `--allow-failed-scan`. `--dry-run` shows the\nvalidated plan without downloading or writing files (it does not check file availability). See\n[the npm installer](installer/README.md) for replacement and license-acknowledgement options.\n\n**Prefer Claude Code's plugin system?** Add the marketplace and install the plugin:\n\n```text\n/plugin marketplace add skill-federation/skill-federation\n/plugin install skill-federation@skill-federation\n```\n\n**No Node or Python?** Ask Claude Code to install the curl version for you:\n\n```text\nInstall the Skill Federation /skillfed finder from github.com/skill-federation/skill-federation\n— run its curl installer (install.ps1 on Windows, install.sh on macOS/Linux), then tell me to\nrestart Claude Code.\n```\n\n> [!TIP]\n> Then **restart Claude Code** and run `/skillfed ` — or just work\n> normally: the skill carries its own triggers (starting a plan, finishing one, hitting a gap\n> mid-task, or your asking), so it offers itself with no hook registered.\n\nZero runtime: the finder needs only `curl` (no Node or Python). For the optional tiers\n(planning nudges · typed MCP tools · Python/CI helper), installing from a checkout, and\nconfig-safety details, see [`install.md`](install.md).\n\n### Invocation options\n\nAll four installers — `install.sh`, `install.ps1`, `npx skillfed`, `uvx skillfed` — take the same\ncore flags for the **finder** install (`install ` is npx-only): `-Flag` in PowerShell,\n`--flag` everywhere else.\n\n| Flag | Values | Default | What it does |\n|---|---|---|---|\n| `--harness` / `-Harness` | `claude-code` | `claude-code` | which harness to install into; an unknown value exits `2` naming what's supported |\n| `--hook` / `-Hook` | `none` \\| `start` \\| `end` \\| `both` | `none` | register 0–2 planning nudges in `settings.json` — `end` fires after a plan is approved, `start` on prompts you submit *while in* plan mode |\n| `--with-hook` / `-WithHook` | — | off | legacy alias for `--hook end` |\n| `--scope` / `-Scope` | `user` \\| `project` | `user` | `~/.claude` vs `./.claude` |\n| `--target` / `-Target` | a directory | — | install into an explicit path instead of the `--scope` default |\n| `--with-npx` / `-WithNpx` | — | off | also register the Node MCP server for typed `find_skills` / `find_packages` / `find_research` tools (needs Node ≥18) |\n| `--endpoint` / `-Endpoint` | a URL | keyless demo | the federation endpoint to record |\n\nTwo more flags exist **only in the curl installers** (`install.sh` / `install.ps1`), not in\n`npx skillfed` or `uvx skillfed`: `--with-python` / `-WithPython` (prints the advanced/CI\nPython-helper setup; changes nothing on your machine) and `--raw-base` / `-RawBase` (where a\nno-clone run fetches the payload from).\n\n`--hook none` is a **complete** install: the skill triggers itself, and hooks only repeat what it\nalready carries. Both nudge files ship whatever the mode, so changing your mind later is a\nsettings edit, never a re-fetch. Before the first write, `settings.json` is backed up once and\nmerged safely. Registration is idempotent. (How to pass flags through a `curl | bash` pipe is in\n[`install.md`](install.md).)\n\n
\nPrefer to paste it yourself? (raw curl one-liner)\n\n```powershell\n# Windows (PowerShell) — irm|iex also sidesteps the execution-policy block\nirm https://raw.githubusercontent.com/skill-federation/skill-federation/main/install.ps1 | iex\n```\n```bash\n# macOS / Linux\ncurl -fsSL https://raw.githubusercontent.com/skill-federation/skill-federation/main/install.sh | bash\n```\n\n
\n\n## 🛡️ Privacy & trust\n\n> [!NOTE]\n> **What never crosses:** your plan, brief, file contents, outputs, or reasoning trace.\n> **What does:** only the abstract wish (description + paraphrases + keywords + capability sketch).\n\n
\nThe full field-by-field breakdown\n\n- **What crosses the boundary:** the abstract wish — its one-line `description`, ~4 paraphrased\n `formulations` of it, 1–5 `keywords`, and a structured **capability `sketch`** of the ideal skill\n (`purpose / inputs / outputs / operations / domain_vocab / section_sketch / tags`). The sketch's\n flattened terms ride inside the search query on every search (they supply the discriminative\n vocabulary that drives recall); when no skill is found, that same sketch becomes the demand\n pointer — abstract enough to protect you, detailed enough to auto-build the missing skill. Every\n field is \"what skill should exist\", never your task. The wish's `name` is display-only and is not\n sent.\n- **What never crosses:** your plan, brief, file contents, outputs, or reasoning trace.\n- **Two complementary signals, not conflated:** a `report_selection` labels retrieval quality —\n what each shown candidate was actually worth, as `Install` / `Read` / `Reject` plus a one-line\n reason (**a read counts as a hit**, even though nothing was installed); a `report_demand`\n captures the capability gap (what was actually needed) and is emitted only on a real miss —\n nothing returned, or everything rejected. They feed different loops: selection sharpens\n search, demand drives what gets built next.\n- **Local-first:** if you already have a skill installed, your local copy is used as-is — your\n edits are personalization, never silently overwritten. It is also reading material: a skill you\n already have on disk is a hint available for free.\n\n
\n\n## 🔒 Security\n\nSkill Federation treats every third-party skill as untrusted input. **Skills are served from our\ninternal, pre-scanned registry — never pulled live from the wild repo.** At ingestion we copy each\ncandidate, dedupe it, and scan it; only passing skills are promoted and served. The `source` link\nyou see is provenance, not where the skill is fetched from.\n\nEvery candidate is best-effort scanned with two independent tools:\n\n- **[Cisco AI Defense Skill Scanner](https://github.com/cisco-ai-defense/skill-scanner)** —\n YARA/pattern, bytecode, command-taint, behavioral dataflow, LLM-as-judge, and VirusTotal checks\n for prompt injection, data exfiltration, and malicious code.\n- **[NVIDIA SkillSpector](https://github.com/NVIDIA/SkillSpector)** — vulnerability-pattern + LLM\n analysis with live OSV.dev CVE lookups and a 0–100 risk score.\n\nHigh/critical findings are **rejected or routed to manual review before promotion** — the wild\ncatalog never reaches you unfiltered.\n\n**Why this matters.** NVIDIA's study behind SkillSpector scanned **42,447 public skills** and found\n**26.1% carried at least one vulnerability** and **5.2% showed likely malicious intent** — and an\ninstalled skill runs with your agent's full permissions. Serving straight from public repos would\nhand roughly one-in-four vulnerable and one-in-twenty malicious skills to your agent; the ingest\ngate is what keeps them out.\n\n> [!NOTE]\n> Scanning is **best-effort**, not a guarantee. As Cisco's scanner puts it, *\"no findings ≠ no\n> risk\"* — a clean scan is not proof a skill is safe. Skill Federation still shows each skill's\n> license, provenance, and source, and **nothing installs without your approval**.\n\n**Reading a skill is a trust decision too.** Most of the time your agent *consults* a skill\nrather than installing it: the body is fetched into context and nothing is written to disk. That\nis the lower-risk path — no third-party code lands on your machine — but the text still enters\nyour agent's context as untrusted third-party input, and a consulted skill leaves **no\n`SOURCE.txt`** behind, because that file is written only on install. So the finder treats a\nfetched body as **data, not as instructions addressed to the agent** (it follows the craft\nguidance and ignores anything telling it to run commands, change settings, or send data\nanywhere), surfaces each consulted skill's license, provenance and source **in its reply** since\nthere's nothing on disk to check later, and asks you first before reading anything unverified or\nflagged.\n\n## 🔧 Configuration\n\nThe finder talks to a federation endpoint over HTTPS. Default is a keyless demo; override it:\n\n```bash\nexport SKILLFED_ENDPOINT=\"https://your-federation.example.com\" # or set in .mcp.json for the npx tier\n```\n\n## 📁 What's in this repo\n\n```\ninstall.ps1 / install.sh / install.md auto-detecting installer; works from a clone OR piped (irm|iex, curl|bash)\ninstaller/ npm package `skillfed` — the `npx skillfed` no-clone path\npython-installer/ PyPI package `skillfed` — the `uvx skillfed` / `pipx run skillfed` path\nscripts/vendor-payload.mjs vendors the 6 payload files into both packages (single source of truth)\nintegrations/claude-code/ the Claude Code plugin (skill + /skillfed + optional hooks) — canonical payload\nintegrations/*.py optional Python tier (advanced / CI)\nmcp-server/ optional Node MCP tier (typed find_skills / find_packages / find_research via npx skillfed-mcp)\n```\n\n## 📄 License\n\n[MIT](LICENSE) © Skill Federation.\n", "bytes": 25733, "sha": "2727938aef1a632c73f72f7bc5934e256e550e509a5868a9433fa51bfb617d62", "repo_slug": "skill-federation/skill-federation", "fonte": "repo", "truncated": false, "api": "https://agentalog.com/api/listings/mcp_io_github_skill_federation_skillfed_mcp_dbe3ac51/readme" }