Post-v1: query/filter on skills/list for large catalogs

[YousefHaggy]

We are building an MCP server that will contain a massive amount of skills. Exposing them all in a skill://index.json is not practical and will leads to context bloat and poor skill selection.

From our server end, we have a mechanism to surface relevant skills based on a query string / passed in context. Today, we can workaround and surface that mechanism through a "discover_skills" tool and returning a list of resource URIs. But relying on a tool being called to discover skills is unideal

Could there be a more idiomatic way to do this in the Skills over MCP extension spec? Perhaps a skills/discover? Or a resources/discover if we are going Skills are just Resources route

This is similar to the "query" parameter proposed for tools in SEP-1821. modelcontextprotocol/modelcontextprotocol#1821

[tobinsouth]

@pja-ant this came up today in a call!

[pja-ant]

Hey @YousefHaggy - excited that you're interested in using this!

Could you elaborate a bit more on how you see skills/discover being different from a tool that is just skills_discover that returns a list of skill URIs?

There's generally a couple of approach that could be taken here depending on your use case:

1. Use the skill://index.json to package high-level skill categories. e.g. imagine you have a code review skill per programming language. Instead of putting them all in the index, you could have a single skill://code-review/SKILL.md in the index, and inside that SKILL.md it says something like: "For language-specific code review guidance, find the relevant skill in skill://code-review/languages" and the model will then go and explore that directory using the resources/directory/read method to find the relevant skill. This should work well for large hierarchical skill catalogues.

2. For unassorted skills, you could have a single skill in the index which just says "Use the skill_search tool to find specific skills related to xyz" and then skill_search is a tool that returns skill URIs that the model can then load.

Or of course, you could use a mix of these.

[YousefHaggy]

@pja-ant Thanks for your reply. Generally I like both of those approaches. One issue is that in approach 2, the model can load the skill URIs that are returned but often does not. We've experienced that even with strong models like Opus 4.8, they often choose to ignore the returned resources and not read them

If the spec specified that MCP clients MUST read returned resource links deterministically instead of relying on the model, perhaps that would solve that problem?

Edit: While there is "priority" in the Resource Annotations, even priority 1 doesn't explicitly require the MCP client to deterministically read the resource, nor is it treated that way in practice.

[t1]

@YousefHaggy: how would an MCP client deterministically decide, if a skill is relevant? E.g., if you tell the LLM to build a web UI, how does the client know that it has to load the "Frontend" skill? String matching will not suffice.

How about some filtering mechanism: some tags that are configured in the project get sent to the server that uses them to filter, e.g. java. WDYT?

[olaservo]

Retitled as a post-v1 proposal. v1's answer for large catalogs is partial/empty skills/list plus skills/get by URI, with server-side search tools as an interim pattern. The proposal to develop here: a query/filter parameter on skills/list (cf. SEP-1821's query-on-tools). Per CONTRIBUTING.md, the vehicle is a decisions.md entry with Status: Proposed. Related: #122.