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…
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-ninjaThat'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.
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.
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.
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'slicenseso you decide.
| 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.
Claude Code — one line:
claude mcp add skill-ninja -- uvx skill-ninjaCursor · VS Code · Antigravity · OpenCode · Gemini CLI · Codex — any client using the standard mcpServers JSON:
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-ninjaBy 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 8000Equivalent 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" }
}
}Pluggable adapters — mix and match:
- GitHub — discovers
SKILL.mdacross 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.
A solid core, growing outward:
- ✅ Core: stdio MCP server + GitHub adapter +
SKILL.mdparsing/validation + FTS5 search +search_skills/download_skilloveranthropics/skills, runnable viauvx. - ✅ 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 buildwheel/sdist, per-client setup docs. (PyPI publish pending.)
PRs toward any of these are welcome.
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.
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.
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.
{ "mcpServers": { "skill-ninja": { "command": "uvx", "args": ["skill-ninja"] } } }