skill-retrieval-mcp
Local semantic search over 374 skills: the agent finds one by describing its task and reads the full text only after choosing.
- 135 ★ on the repository
- Last commit
Extended access
Why this level
- The server runs local code and downloads a corpus from the network.
- Skill texts from third-party repositories enter the agent context and may contain harmful instructions.
Install
- Works in
Manual install
pip install "skill-retrieval-mcp[local,hf]"The first install command from the README. Then `skill-mcp pull --include-index` downloads the corpus and `skill-mcp init` registers the server with detected agents.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The server runs local code and downloads a corpus from the network.
- Skill texts from third-party repositories enter the agent context and may contain harmful instructions.
This is third-party code. Review the repository files before installing.
What it does
Skill-retrieval-mcp is an MCP server that stores 374 skills from eight public repositories and searches them by meaning. Search returns short descriptions, and the agent fetches the full text of one chosen skill with a separate `get_skill` call, so the whole library never enters the context at once. The index is built locally with FAISS and search makes no external API calls. Each skill records its source repository, link and SPDX licence. Your own skills from a folder of `SKILL.md` files are added with `skill-mcp import`.
Who it is for. Developers on Claude Code, Codex or Cursor who have more skills than fit into the agent context.
Good fit when
- Mid-task, the agent needs a skill on a topic the user cannot name.
- A library of hundreds of skills does not fit into the descriptions loaded at startup.
- You need to find a skill by an exact command or error text through `keyword_search`.
- A team builds its own skill base and wants the same search over it.
Not a fit when
- You have about ten skills and the agent already handles their descriptions.
- Downloading the corpus from Hugging Face and keeping the data locally is not allowed.
- Skills from other repositories cannot enter the working context unreviewed.
Example request
Find a skill about autoscaling pods on CPU and memory, show the descriptions and open the best fit.MCP
- Transport
- stdio
- Authentication
- not required
Environment variables
SKILL_MCP_DATA_DIR- Data folder used instead of `~/.skill-mcp`.
OPENAI_API_KEYsecret- Needed only for the `openai` embedding backend.
Limitations
The corpus and prebuilt index are downloaded from Hugging Face with `skill-mcp pull --include-index`, and the first install takes about two minutes. The prebuilt index uses `all-MiniLM-L6-v2`; another embedding backend (`openai`, `ollama`) needs an index rebuild. The agent config needs an absolute path to `skill-mcp` and an explicit `--data-dir` before `serve`, otherwise the server starts and silently answers with nothing. Skill texts come from third-party repositories, so read a chosen skill before following its steps.
How to disable. Remove the `skill-retrieval` entry from the agent MCP configuration and the data folder (`~/.skill-mcp` by default). Uninstall the package with `pip uninstall skill-retrieval-mcp`.
FAQ
Which tools does the server provide?
Four: `search_skills` searches by meaning, `keyword_search` matches exact text, `get_skill` returns the full text and `list_categories` shows topics with skill counts.
Is an API key required?
No. Embeddings come from the local `all-MiniLM-L6-v2` model by default; `OPENAI_API_KEY` is needed only after switching to the `openai` backend.
How do I add my own skills?
Put them in a folder of `SKILL.md` files and run `skill-mcp import --source directory --path ~/my-skills/`. The index updates itself and duplicates with the corpus are removed.
Where do the corpus skills come from?
From eight public repositories such as google/skills, anthropics/skills and obra/superpowers. Each licence was checked before import, and repositories without redistribution rights were left out.
How much does the corpus weigh?
The first install takes about two minutes of download. One skill averages about 2,400 tokens, while five search summaries cost a few hundred.
Discussion
No questions or reviews yet.
Related
MCP serversClaude Skills MCP: semantic search for skills
Claude Skills MCP
An MCP server with vector search: the agent describes a task and gets matching skills from the Anthropic and K-Dense collections
Skill search from inside the conversation: the agent finds a SKILL.md, reads it and applies it with no prior install
Meta Skill (ms)
Meta Skill
Meta Skill (ms) keeps skills locally in SQLite and Git, searches them with a hybrid index and serves agents over MCP
A CLI and MCP server for Agent Skills: spec validation, installs from GitHub and on-demand loading of the right skill
An MCP server that opens SKILL.md skills to clients without native support, such as Codex, Copilot and Cursor
Graph of Skills builds a dependency graph over SKILL.md files and serves the agent only the skills a task needs, through MCP
README in short
The README argues that search beats manual installation, because the agent discovers skills the user did not know existed. On 43 held-out queries phrased as agent tasks, the shipped corpus returns the right skill at rank 1 in 81.4% of cases.