skill-ninja 0.1.0

MCP server that gives any AI agent just-in-time Agent Skills via semantic/lexical search over a federated catalog.

🥷 skill-ninja

Give your AI agent just-in-time skills. One MCP server. Any IDE.

skill-ninja lets your AI agent find and pull the exact Agent Skill it needs — the moment it needs it — from across GitHub, agentskills.io, and your own folders. No pre-installing. No context bloat. Works in any MCP client: Claude Code, Cursor, VS Code, OpenCode, Antigravity, Gemini CLI, Codex…

---

⚡ Install in one sentence

Just tell your agent:

"Install the MCP server at https://github.com/elhumbertoz/skill-ninja"

It reads this README, runs the command below, and you're done. Or do it yourself in one line:

# Claude Code
claude mcp add skill-ninja -- uvx skill-ninja

# Just run it (zero-install via uv)
uvx skill-ninja

That's the whole install. No model download. No database to set up. No API key. It starts instantly. 🚀

_{⭐ Find it handy? Star the repo — it helps other devs discover it.}

---

The problem it kills

You ask your agent to edit an .xlsx file. It doesn't know the right approach, so it guesses — wrong library, broken formatting, an afternoon lost.

A skill that teaches it exactly how to do this already exists. But skills are scattered across dozens of repos and registries, and wiring them in is manual. Pre-installing them all? That bloats your context with stuff you don't need 99% of the time.

skill-ninja flips it:

Without skill-ninja	With skill-ninja
Hunt GitHub for the right skill	Agent calls search_skills("xlsx")
Copy files into your skills folder	Agent pulls the proven skill into context
Hope it's current and correct	It's fetched from origin, version-pinned
Repeat for every task	One tool. Every task. Any IDE.

Your agent gains expertise on demand — it carries one cheap search tool and brings in only the specific skill it needs, when it needs it.

---

Use it

Once registered, just talk to your agent in plain language:

• 💬 "Find a skill for editing xlsx files and use it."
• 💬 "Search skills about web-app testing and download the best one."
• 💬 "What skills have I already downloaded?"

Under the hood it chains the MCP tools below: search → download → read.

---

How it works

Two layers — that's the trick that keeps it cheap, fast, and offline-first:

Layer	What	Cost
🔍 Metadata index	name + description + source for every discovered skill, without downloading the bundle	light — search runs here
📦 Local store	full bundles (SKILL.md + scripts/ + references/ + assets/) you actually download	heavy — fetched on demand

Search hits the lightweight index; download materializes the full skill. Search is lexical (SQLite FTS5) by default — no model downloads, no API keys, works offline.

Want fuzzier matching? An opt-in semantic / hybrid backend (pip install 'skill-ninja[semantic]', then SKILL_NINJA_SEARCH=hybrid) adds local embeddings via fastembed — so "crunch some numbers in a workbook" finds the xlsx skill even though it never says "spreadsheet." If the extra isn't installed, it silently stays lexical.

Fetcher, not mirror. skill-ninja always downloads from the original source and caches locally for you — like a package manager (apt/npm). It never re-hosts skills, and surfaces each skill's license so you decide.

---

MCP tools

Tool	Input	Output
search_skills	query, top_k?, filters? (category/source/license)	ranked skills with skill_id + metadata
get_skill	skill_id	SKILL.md content + bundle file list
read_skill_file	skill_id, path	content of a bundled resource
download_skill	skill_id, dest?	local path + manifest
list_local_skills	—	already-downloaded skills
list_sources / add_source / remove_source	url?, type?	source state
refresh_catalog	source?	re-index summary

Everything returns structured JSON so the agent can decide the next move.

---

Works in your IDE

Claude Code — one line:

claude mcp add skill-ninja -- uvx skill-ninja

Cursor · VS Code · Antigravity · OpenCode · Gemini CLI · Codex — any client using the standard mcpServers JSON:

{
  "mcpServers": {
    "skill-ninja": {
      "command": "uvx",
      "args": ["skill-ninja"]
    }
  }
}

Each client stores this config in a different place (a settings file, a .mcp.json, or a UI). Check your client's MCP docs for where it goes.

Prefer the bleeding edge? Install straight from source:

uvx --from git+https://github.com/elhumbertoz/skill-ninja skill-ninja

Remote / shared (HTTP transport)

By default skill-ninja talks stdio (one server per client, local). To run it once and share it over the network, start it on an HTTP transport:

# Streamable-HTTP (recommended) — serves the MCP endpoint at http://<host>:<port>/mcp
skill-ninja --transport streamable-http --host 0.0.0.0 --port 8000

# or the legacy SSE transport (http://<host>:<port>/sse)
skill-ninja --transport sse --port 8000

Equivalent env vars: SKILL_NINJA_TRANSPORT, SKILL_NINJA_HOST, SKILL_NINJA_PORT. Then point any HTTP-capable MCP client at the URL:

{
  "mcpServers": {
    "skill-ninja": { "url": "http://your-host:8000/mcp" }
  }
}

---

Sources

Pluggable adapters — mix and match:

• GitHub — discovers SKILL.md across a repo, monorepo-aware via the Git Trees API. Reference: anthropics/skills.
• Generic git — shallow clone of any git URL (GitLab, Codeberg, self-hosted…).
• Local filesystem — index your own skill folders.

Add or remove sources at runtime with the add_source / remove_source tools; refresh is incremental (unchanged sources are skipped).

The community site agentskills.io is not a source here — it's documentation + a showcase of products that support the format, not a catalog of downloadable skills. Skills live in git repos, which the adapters above already cover.

---

Roadmap

A solid core, growing outward:

• ✅ Core: stdio MCP server + GitHub adapter + SKILL.md parsing/validation + FTS5 search + search_skills / download_skill over anthropics/skills, runnable via uvx.
• ✅ Multi-source: generic git + local FS adapters; source management (add_source/remove_source); incremental refresh.
• ✅ Search quality: opt-in semantic backend (fastembed) + hybrid (lexical + vector, RRF) search, filters, graceful fallback to lexical.
• ✅ DX & distribution: stdio + HTTP/SSE transports, uv build wheel/sdist, per-client setup docs. (PyPI publish pending.)

PRs toward any of these are welcome.

---

Tech stack

Python 3.12+ · uv · FastMCP · SQLite + FTS5 (search) · httpx + GitHub REST · git CLI (generic-git source). Optional semantic search via fastembed + numpy, default model BAAI/bge-small-en-v1.5 (skill-ninja[semantic]). A TypeScript/Node port is a viable alternative if npx distribution is preferred.

---

Contributing

Contributions are welcome — new source adapters and verified per-client setup docs are especially valuable. Open an issue to discuss, or send a PR.

Format background: agent-skills-reference.md · full design: CLAUDE.md.

---

License

Apache-2.0 — aligned with the Agent Skills ecosystem.

skill-ninja indexes and downloads third-party skills but does not redistribute them; each skill keeps its own license, which skill-ninja surfaces in search results.