Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@skill-router-mcp recommend skills for code review"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Skill Router MCP is a local, read-only router for large collections of agent skills. It indexes installed SKILL.md files, searches their metadata and workflows, reports duplicate definitions, and recommends a transparent candidate set to an AI agent.
The router does not execute skills and does not make the final choice. It returns:
primary candidates;
complementary skills;
additional candidates that might otherwise be hidden by a small result limit;
invocation mode (automatic, manual-only, or unspecified);
matching evidence and duplicate paths.
No LLM, embedding API, account, telemetry, or network call is used for routing.
inventory_skills — summarizes indexed roots, invocation modes, duplicate names, and read errors.
search_skills — deterministic scored search for a capability or task.
recommend_skills — proposes primary, complementary, and additional candidates while leaving the decision to the agent.
explain_skill — returns metadata and duplicate locations for an exact skill name.
All tools are declared read-only and idempotent.
Related MCP server: skill-depot
Node.js 20 or newer.
An MCP client with local stdio support, such as Cursor.
npm install -g https://github.com/Agent-Nova-107/skill-router-mcp/archive/refs/heads/main.tar.gzAdd the server to Cursor's user MCP configuration:
{
"mcpServers": {
"skill-router": {
"command": "skill-router-mcp"
}
}
}Install the optional agent skill:
npx skills add Agent-Nova-107/skill-router-mcp --global --agent cursor --yesCopy cursor/skill-routing.mdc to ~/.cursor/rules/skill-routing.mdc if you want Cursor to consult the router automatically for ambiguous or complex tasks.
Restart Cursor after changing MCP configuration.
By default the server checks:
~/.agents/skills/
~/.cursor/skills/
<current-directory>/.agents/skills/
<current-directory>/.cursor/skills/Override this list with SKILL_ROUTER_PATHS, using the operating system's normal path separator (; on Windows, : on Unix):
$env:SKILL_ROUTER_PATHS = "C:\skills;D:\team-skills"Symbolic links are not followed. Skill files larger than 256 KiB and traversal deeper than eight directories are rejected.
Routing is deterministic:
Parse YAML frontmatter and invocation metadata.
Normalize English and French task terms.
Score name, description, workflow text, and lifecycle intent separately.
Collapse duplicate names while exposing every duplicate path.
Return a broad candidate pool divided into primary, complementary, and additional sections.
Scores rank candidates; they are not probabilities or quality ratings.
Tools accept task text and skill names, not arbitrary filesystem paths.
The server only reads the configured skill roots.
Prompt text inside a skill is treated as searchable data, never executed.
Keyword routing can miss semantic relationships or rank generic descriptions too highly.
A recommendation proves relevance only, not quality, freshness, compatibility, or safety.
The AI agent must inspect the task, codebase, and selected skill before acting.
npm ci
npm run check
npm test
npm run buildTo smoke-test the stdio server with the MCP Inspector:
npx @modelcontextprotocol/inspector node dist/index.jsMIT
Return metadata and duplicate locations for an exact installed skill name without executing it or dumping its full prompt.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Exact skill name |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is well covered. The description adds valuable context beyond annotations by clarifying the tool does not execute the skill or dump its full prompt, and that it requires an exact match. This effectively communicates key behaviors without contradicting the annotations. It doesn't address error behavior for non-existent skill names or exact-match failure cases, which would push it to a 5.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is a single concise sentence front-loaded with the primary purpose, followed by two clarifying exclusions. Every word earns its place, with zero filler. This is an exemplar of efficient, well-structured tool documentation.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a read-only metadata lookup tool with a single parameter, strong annotations, and no output schema, the description is largely complete. It covers the core function and what it deliberately avoids (execution, full prompt dump). Minor gap: it doesn't describe what a failed lookup (nonexistent name) returns, which could matter for an agent handling errors. With simple tool complexity, this is near-complete but not exhaustive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% (the single 'name' parameter is documented as 'Exact skill name' in the schema itself). The description adds marginal value by reinforcing the 'exact' constraint on the name, but since the schema already documents the parameter fully and there's only one trivial string parameter, the baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses specific verb+resource ('Return metadata and duplicate locations for an exact installed skill name') and clearly distinguishes behavior from related operations by stating 'without executing it or dumping its full prompt.' This effectively differentiates from sibling tools like search_skills which imply broader search. However, 'metadata' is somewhat vague about what specific attributes are returned, and the exact distinction from siblings like inventory_skills could be sharper.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'exact installed skill name' and clarifying it does NOT execute or dump full prompts, which guides an agent toward when this tool is appropriate versus inventory (listing all) or search/recommend (finding). However, it doesn't explicitly name alternative sibling tools or give explicit 'when/when-not to use' guidance, so it stops short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Index installed SKILL.md files and summarize roots, invocation modes, duplicate names, and read errors. Read-only.
| Name | Required | Description | Default |
|---|---|---|---|
| includeDuplicatePaths | No | Include all paths for duplicate skill names |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, covering the safety profile. The description redundantly restates 'Read-only' but adds useful context about what the tool reports (duplicate names, read errors). It doesn't contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two concise sentences that efficiently convey the tool's purpose and outputs. The 'Read-only' clarifying note is slightly redundant given the annotations but harmless. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter, read-only, idempotent tool with a fully-covered schema, the description covers the essential behavior adequately. It describes what gets indexed and what summaries are produced. Could mention the format of the summary output, but given zero params required and no nested objects, this is complete enough for an agent to use confidently.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so the single parameter (includeDuplicatePaths) is fully documented in the schema itself. The description mentions 'duplicate names' as an output, which loosely relates to the parameter, but the schema already explains it clearly. Baseline 3 is appropriate when the schema handles parameter documentation.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Index') with a clear resource ('installed SKILL.md files') and enumerates the specific outputs (roots, invocation modes, duplicate names, read errors). This distinguishes it well from sibling tools like search_skills and recommend_skills, though it doesn't explicitly name them.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies this is an administrative/inspection tool and states it is 'Read-only,' but it doesn't explicitly say when to use it over alternatives like search_skills or explain_skill. The context is clear enough for an agent to infer it's for inventorying installed skills vs searching/recommending, but no explicit exclusions are given.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recommend primary, complementary, and additional installed skills for a task. Advisory only; the AI agent retains the final decision and additional candidates are not hidden.
| Name | Required | Description | Default |
|---|---|---|---|
| task | Yes | Complete task description | |
| primaryLimit | No | Maximum primary recommendations; not a total candidate limit | |
| candidateLimit | No | Total candidate pool retained across all sections |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so the safety profile is fully covered by structured data. The description adds value by disclosing the advisory-only semantics and that additional candidates are retained (not filtered out or hidden), which is a meaningful behavioral trait. However, it doesn't describe return format, ordering, or how limits interact across sections beyond the schema's param descriptions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, both earning their place. The first states the core purpose and the second clarifies the critical advisory/non-hiding behavior. No filler or repetition of what schema/annotations already provide. Loses one point only for not front-loading a strong verb phrase more prominently.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a non-destructive, advisory tool with excellent annotations and 100% schema coverage, the description is appropriately complete. It covers purpose, scope (installed skills), and key behavioral caveat (advisory only, candidates not hidden). No output schema exists, so return values aren't specified, but for a recommendation tool the structure is reasonably inferable from the schema coverage. Complete enough for safe invocation.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, so the schema already documents all three parameters (task, primaryLimit, candidateLimit) with descriptions. The description adds marginal value by clarifying these are installed skills and that candidates aren't hidden. Baseline 3 is appropriate since the schema carries the parameter documentation burden adequately.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'recommend' with specific resources (primary, complementary, additional skills) for a task. It differentiates from siblings like inventory_skills (listing) and search_skills (finding specific skills) by framing the deliverable as a curated recommendation flow rather than raw enumeration. Could be slightly stronger by naming that it works across 'installed skills' explicitly versus search across all.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context of when to use this tool (for a task needing skill recommendations) and importantly clarifies the advisory nature — the agent retains final decision and candidates aren't hidden. It implicitly distinguishes from siblings (inventory lists skills plainly, search finds specific ones) though it doesn't explicitly name alternative tools. A clear when-to-use context with implied exclusions merits a solid score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search installed skills deterministically by task terms. Returns scored candidates and reasons without choosing for the agent.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Maximum unique skill names returned | |
| query | Yes | Task or capability to search for |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true, destructiveHint=false, and idempotentHint=true, so the safety profile is covered. The description adds 'deterministically' (implying stable, reproducible results) and 'scored candidates and reasons' (informing the agent about output shape), which enriches behavioral understanding beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, zero waste. Each phrase earns its place: 'deterministically' conveys behavior, 'scored candidates and reasons' conveys output, and 'without choosing for the agent' conveys role boundary.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple 2-param read-only search tool with 100% schema coverage and no output schema, the description adequately covers purpose, behavior, and output shape. It could mention return format expectations (e.g., result ordering) but is largely complete for the tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, so both query and limit parameters are already well documented in the schema. The description doesn't add semantic detail beyond what the schema provides, but it does clarify the deterministic scoring/reasons output. Baseline 3 is appropriate given full schema coverage.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it searches installed skills 'deterministically by task terms.' It emphasizes that it returns 'scored candidates and reasons without choosing for the agent,' which defines its scope precisely. This distinguishes it from siblings like recommend_skills (which presumably chooses/recommends) and inventory_skills (which lists).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The phrase 'without choosing for the agent' implies the tool returns candidates for agent review rather than auto-selecting, which gives a clear usage context. However, it doesn't explicitly state when to prefer this over recommend_skills or inventory_skills, nor provides any when-not-to-use exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0explain_skillinventory_skillsrecommend_skillssearch_skillsScored across 4 tools
Tools are mostly distinct in purpose: inventory summarizes the index, search finds candidates, recommend provides ranked suggestions, and explain returns metadata. However, search_skills and recommend_skills overlap notably in that both surface candidate skills for a task, with the difference (scored candidates vs. categorized recommendations) subtle enough that an agent could misselect. inventory_skills and explain_skill also both touch metadata/duplicate info.
All four tools follow a consistent verb_noun pattern (inventory, search, recommend, explain) that is clear and readable. The verbs are varied but each communicates a distinct action well, and the noun 'skills' is consistent. Minor inconsistency: 'inventory' as a verb is slightly unconventional vs. the more standard 'list', but the pattern remains coherent.
Four tools is a reasonable, focused count for a skill-routing server whose purpose is discovery/indexing/advisory. Each tool earns its place covering distinct stages of the workflow. Could arguably be slightly slim, but it's well-scoped and not overly heavy.
The surface covers indexing, searching, recommending, and explaining skills, which covers the core discovery workflow well. However, there's no tool for skill management operations (e.g., installing, removing, or updating skills), and no filter-by-category listing tool—gaps that agents might hit when they need to act on skills rather than just discover them. Still, for a routing/advisory purpose the surface is largely complete.
Search, fetch, lint, and install Agent Skills (SKILL.md) from the SkillMD registry.
Search your team's shared AI-skill library, get install commands, and save skills from your agent.
Search, install and submit Markdown skills for AI agents; private Brain files when signed in.
Find, inspect and install reviewed reusable AI-agent capabilities from superskill.sh.