Finding the Right Skill Without Flooding the Agent
In Agent Skills, discovery is not a catalog-browsing problem in disguise. It is a routing problem: given a natural-language task, how can the MCP server offer a small set of plausible skills, load enough instruction to choose among them, and avoid filling the agent's context with material that has not yet earned its place? The answer combines intent search with progressive disclosure, so readers can understand not only what the agent receives but why each additional layer is requested.
Search turns descriptions into routing signals
The MCP server builds its search index from the generated registry rather than from every reference file. Each skill contributes a name, category, description, a shorter usage hint, and trigger text extracted from recognizable phrases such as “Triggers on,” “Use when,” and “Keywords.” The search engine then compares a natural-language intent against those fields with different weights. Names and explicit triggers carry more routing influence than broad descriptions, while category provides a lighter contextual signal.
This design fits how people describe work. A user is more likely to say “review accessibility issues in my UI” or “plan a migration from a monolith” than to know the exact catalog name. Token-based fuzzy search lets each meaningful word contribute even when the phrase does not match a skill title exactly. The server returns a small ranked set—up to five candidates—with a score, a qualitative match band, and a usage hint. That is enough for an agent to compare likely routes without downloading the full instruction corpus for every candidate.
The score is a routing signal, not a verdict. A fuzzy engine can always find something that resembles a query, even when the catalog has no good answer. Agent Skills addresses that failure mode by assigning match-quality bands and dropping weak results. An empty result is useful information: it tells the agent that it should try different terms or proceed without a catalog skill rather than treating the weakest candidate as permission to act. The design prefers a visible absence of guidance to a misleading appearance of certainty, especially at the first routing decision.
The description's negative scope provides a second filter. A skill can say that it applies to accessibility but not SEO, to AWS but not other cloud providers, or to security guidance but not general debugging. Those boundaries are not decorative. They help an agent distinguish two entries that share vocabulary while serving different decisions. A user asking for performance optimization may mention React components, but that does not make a composition-pattern skill relevant. A user asking for threat modeling may mention security, but a secure-coding checklist is not automatically the right route.
The search response also deliberately omits the full description when the usage hint is enough for comparison. Re-sending the same long text at discovery would spend context before the agent has chosen a candidate.