Site Search
by
Search tuning for ecommerce teams: read the queries returning nothing or the wrong thing, then add the synonyms, redirects and pinned results that fix them.
Site search is used by a small share of visitors who convert several times better than everyone else, which makes a failed search unusually expensive. It also fails silently: a customer searching a term your catalog calls something else gets no results, leaves, and appears in your analytics as a bounce with no explanation. The fix is almost always a synonym or a redirect rather than anything structural. This skill reads the queries returning nothing or the wrong thing and adds the rules that fix them.
What It Does
- Finds the queries returning zero results, ranked by how often they are searched.
- Detects queries that return results nobody clicks, which fail less visibly.
- Maps customer vocabulary to your catalog's naming.
- Identifies the query that should be a redirect rather than a result set.
- Spots demand for products you do not carry, from repeated failed searches.
- Adds the synonyms, redirects and pinned result rules, with the query they fix.
Use Cases
- Fix the searches returning nothing on products you actually sell.
- Catch the query returning results that nobody clicks.
- Redirect a category search to the category page rather than a product list.
- See the demand for products you do not stock yet.
Example Session
What is broken in our site search?
Four fixes cover most of it. Two are one-line synonyms.
- Query | Monthly searches | Result | Fix | Worth
- jumper | 410 | Zero results | Synonym to hoodie | $14,000 per quarter
- waterproof | 280 | 31 results, 2% clicked | Pin the 3 rain styles | $9,000 per quarter
- gift card | 240 | Zero results | Redirect to gift card page | $7,000 per quarter
- wool socks | 190 | Zero results | Not carried | Stock signal
Four hundred people a month search for a jumper and find nothing, because your catalog calls it a hoodie. That is one synonym. The waterproof query is the sneaky one: it returns thirty-one results so it looks like it worked, and almost nobody clicks, because the actually waterproof items are on page two. Wool socks is not a search problem, it is a buying signal.
Why This Beats Prompting It Yourself
Zero Result Queries vs Queries That Look Fine: The Hidden Risk
A generic prompt reads the zero-results report, which every search tool provides, and fixes what it finds. The more expensive failures never appear there: a query returning thirty-one items that nobody clicks looks successful in every report. Customers searched, saw a page of wrong things, and left.
When You Still Need The Search As A Buying Signal
A hundred and ninety people a month searching for something you do not sell is not a search problem to fix, it is demand you can see before anyone else does. This skill separates the queries that need a rule from the queries that belong in a buying conversation, and that second list is the one nobody is reading today.
Known Limitations
Click-through on search results needs search analytics with result interaction, and without it the skill works from zero-result queries alone and says what it cannot see. Synonym suggestions are generated from customer vocabulary and should be reviewed before applying in ambiguous categories. It writes the rules and does not deploy them to your search provider.
Install It
- Download the ZIP.
It is free and there is no account to create. - Unzip it into your agent's skills folder.
Claude Code reads ~/.claude/skills/, which is hidden by default: the command in the folder block opens it. Other agents scan their own directory, so drop the same folder there instead. - Ask your agent to use it.
Restart the agent if it was already running, then it picks the skill up with no config.
skills folder
Copy
~/.claude/skills/site-search/
SKILL.md
references/synonym-map.md
rules/
# one file per run, with the rules and the query
# macOS: create the folder and open it in Finder
mkdir -p ~/.claude/skills && open ~/.claude/skills
# Windows: paste in the Explorer address bar
%USERPROFILE%\.claude\skills\Frequently asked questions
How is this different from my search tool's zero-results report?
That report covers the visible half. This also finds queries that return plenty of results nobody clicks, which fail invisibly and are usually worth more. It also separates missing-product demand from rule problems, which a zero-results list cannot do.
Which agents does the skill run in?
Any agent that supports the open SKILL.md format: Claude Code, Cursor, Codex CLI, GitHub Copilot, Gemini CLI, Manus, Grok and others load it unmodified. The format is portable, the location is not. Each agent scans its own skills directory, so you drop the same folder into whichever one yours uses. There is no config file to edit and no API key to provision.
What does it need connected to work?
Search query logs with result counts, ideally with click and conversion data, plus your product catalog. Order data lets it size each fix in revenue rather than in searches.
How is a failed search worth $14,000?
Search users convert several times better than browsers, so each failed search costs more than an average lost session. Four hundred and ten searches a month at that conversion rate and your average order value is the arithmetic, and the fix is a single synonym.
Should I apply every synonym it suggests?
Review them in ambiguous categories. Customer vocabulary occasionally maps a word onto two different products, and a synonym applied there makes search worse. The output flags the ones where the mapping is not clean.
What is included with the skill?
The skill itself, the synonym map reference, the rule format, and the query classification logic. It is free and security scanned. We re-publish the ZIP when the map changes, so download it again if your rules start shifting.
A zero-result search is a sale you can still recover.
Polar joins search behavior to orders and inventory in one semantic layer, so the synonyms and redirects you add point at stock that exists and converts.
<script type="application/ld+json">{"@context":"https://schema.org","@type":"FAQPage","mainEntity":[{"@type":"Question","name":"How is this different from my search tool's zero-results report?","acceptedAnswer":{"@type":"Answer","text":"That report covers the visible half. This also finds queries that return plenty of results nobody clicks, which fail invisibly and are usually worth more. It also separates missing-product demand from rule problems, which a zero-results list cannot do."}},{"@type":"Question","name":"Which agents does the skill run in?","acceptedAnswer":{"@type":"Answer","text":"Any agent that supports the open SKILL.md format: Claude Code, Cursor, Codex CLI, GitHub Copilot, Gemini CLI, Manus, Grok and others load it unmodified. The format is portable, the location is not. Each agent scans its own skills directory, so you drop the same folder into whichever one yours uses. There is no config file to edit and no API key to provision."}},{"@type":"Question","name":"What does it need connected to work?","acceptedAnswer":{"@type":"Answer","text":"Search query logs with result counts, ideally with click and conversion data, plus your product catalog. Order data lets it size each fix in revenue rather than in searches."}},{"@type":"Question","name":"How is a failed search worth $14,000?","acceptedAnswer":{"@type":"Answer","text":"Search users convert several times better than browsers, so each failed search costs more than an average lost session. Four hundred and ten searches a month at that conversion rate and your average order value is the arithmetic, and the fix is a single synonym."}},{"@type":"Question","name":"Should I apply every synonym it suggests?","acceptedAnswer":{"@type":"Answer","text":"Review them in ambiguous categories. Customer vocabulary occasionally maps a word onto two different products, and a synonym applied there makes search worse. The output flags the ones where the mapping is not clean."}},{"@type":"Question","name":"What is included with the skill?","acceptedAnswer":{"@type":"Answer","text":"The skill itself, the synonym map reference, the rule format, and the query classification logic. It is free and security scanned. We re-publish the ZIP when the map changes, so download it again if your rules start shifting."}}]}</script>