How search finds the right skill

Type “make my agent read receipts” into the search box and you’ll land on a PDF-extraction skill even though the word “PDF” never appears in your query. That’s not a lucky keyword match. It’s a second search happening underneath the obvious one, and understanding how it works changes how you should write a skill’s description.

Two searches, not one

Every query against the registry runs two ways at once: a lexical match against titles, descriptions, and tags, and a semantic match against a vector index built from the same text. The lexical side catches exact terms. The semantic side catches everything the lexical side can’t: synonyms, typos, a different phrasing of the same intent, a request in a different language than the skill was written in.

The semantic half works by embedding, converting text into a vector that represents its meaning, not its exact wording. Skills get embedded once at publish time; your query gets embedded the moment you search. The system then finds the skill vectors closest to your query vector. “Read receipts” and “extract text from PDFs” land near each other in that space even though they share no words, because the model embedding them is multilingual and trained on meaning rather than string overlap.

This is why a search for “pull tables out of a scanned invoice” can surface a skill titled pdf-extract with a description about pdfplumber. Nobody wrote “scanned invoice” anywhere in that skill’s frontmatter. The embedding doesn’t need them to.

Degrading on purpose

Semantic search depends on an external model call, and external calls fail sometimes: a timeout, a cold start, a service hiccup. When that happens, search doesn’t error out or return nothing. It falls back to lexical-only results and keeps going. You’ll never see a blank results page because the embedding step had a bad moment; you’ll see the same results you’d get from a plain keyword search, which is a fine fallback, just a narrower one.

This matters for how you think about search reliability: the lexical layer is the floor, always available, exact-match reliable. The semantic layer is what raises the ceiling, catching the queries that don’t share vocabulary with your skill’s text. You get semantic matching most of the time and correct-but-narrower matching the rest of the time. Neither path is broken; one is just less generous than the other.

What actually gets embedded

Here’s the part that should change how you write a description: the text that gets embedded isn’t your whole SKILL.md. It’s a specific, weighted slice of it, description first and repeated, then a short excerpt of the body, then a bit of the README if you have one. The description carries the most weight in that slice by a wide margin.

That means the advice from writing a good description for a human or an agent to read applies just as directly to search, but for a different reason. It’s not only that a vague description fails to inform a reader. It’s that a vague description embeds into a vague region of the vector space, one that sits near dozens of other vaguely-described skills instead of near the specific queries that should find yours.

Compare two descriptions for the same skill:

description: Works with PDF files.

against:

description: Extracts text and tables from PDF files using pdfplumber, with page-range and layout options.

The first embeds into a broad, crowded region: “PDF,” “files,” and not much else to anchor on. It’ll show up for exact-match queries containing the word “PDF” and rank poorly for anything that doesn’t. The second embeds with enough specific signal, “extracts,” “tables,” “pdfplumber,” “layout” that it lands near a narrower, more relevant set of queries: “get structured data out of a PDF,” “table extraction from documents,” even “pdfplumber alternative.”

Why leading with the body backfires

An earlier version of the registry’s embedding logic leaned harder on a skill’s full body text. It didn’t help; it hurt. Every skill that mentioned “video” anywhere in its instructions clustered together regardless of what the skill actually did, and every skill that mentioned “design” did the same. Broad topic words in a long body text drown out the specific intent a short, well-written description carries. The fix was to put the description first, repeat it, and only append a capped slice of the body afterward as supporting context, not the main signal.

The practical takeaway: don’t pad a thin description by hoping the body will carry the search weight. It won’t. Front-load the description with the specific operation, the tool or format involved, and the concrete outcome. That’s the text doing the most work for both the person reading it and the vector index representing it.

Searching in your own words

None of this requires you to think about vectors when you’re the one searching, only when you’re the one publishing. As a searcher, the practical result is that you don’t need registry vocabulary to find something. Describe the outcome you want in plain language, typos included, and the semantic layer does the translation between your words and the author’s. If that still comes up short, fall back to a narrower, more literal term. Between the two, one of them almost always gets you to the right skill.