marketplace-search-and-ranking
Skill1 starsChanged 18 days agoMITView on GitHub
Index purchasable catalog units and rank them with text relevance, facets, stock, and language-aware matching for Persian and other languages. Use when building marketplace search, filters, relevance, or multilingual product discovery.
In this repository28 other files it gives its agents.
- b2b-pricingSkill
- catalog-import-and-migrationSkill
- checkout-ux-and-conversionSkill
- conversion-event-trackingSkill
- ecommerce-seo-structured-dataSkill
- fraud-and-risk-basicsSkill
- google-merchant-product-feedsSkill
- headless-nextjs-storefrontSkill
- inventory-and-multi-warehouseSkill
- iranian-payment-gatewaysSkill
- mcp-store-toolingSkill
- multi-vendor-payoutsSkill
- order-and-webhook-reliabilitySkill
- payment-gateway-integrationSkill
- product-catalog-modelingSkill
- product-description-guardrailsSkill
- returns-and-refundsSkill
- rtl-and-persian-localizationSkill
- shopify-app-developmentSkill
- storefront-accessibilitySkill
- storefront-performanceSkill
- stripe-paymentsSkill
- subscription-billingSkill
- tax-and-shippingSkill
- vector-product-searchSkill
- woocommerce-plugin-developmentSkill
- woocommerce-rest-apiSkill
- wordpress-plugin-securitySkill
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 5 are distinctive, and 0 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈5
Distinctive · estimate
This author's own choices. Worth a look.
0
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 36
Do not index a display string that already contains a currency symbol as the price.
- Distinctive: line 41
If the normalized query equals a SKU or GTIN, return that unit first.
- Distinctive: line 56
Use a language-specific analyzer.
- Distinctive: line 65
Use these as a starting point, then change them when labeled queries show a miss:
- Distinctive: line 73
Write the formula down in the service that serves results.
≈ “Common” is an estimate: at least 1 in 5 of the 372,429 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
Marketplace search and ranking
Use this skill for product discovery in a marketplace or catalog. It does not assume a particular search engine. Apply the same document and ranking rules whether the index is a dedicated search service or a database index. Text normalization for Persian and mixed digits lives in scripts/normalize-search-text.mjs. Field and scoring details are in the ranking notes.
Procedure
- Index the purchasable unit. A simple product is one document. Each variant is its own document, with parent title, brand, and categories copied onto it. Do not index only the parent when prices and stock differ by variant.
- Normalize text the same way at index time and query time. Run
normalize-search-text.mjslogic before analysis. - Give every facet a stable id and a localized label. Filter on the id.
- Rank with text relevance first, then stock and explicit business rules. Start from the factors in the ranking notes and tune them with labeled queries. Do not treat those factors as measured conversion rates.
- Return a keyset (search-after) page, not a deep offset. Offsets skip or repeat documents when the index changes.
Document
Each document needs:
unit_idandskuparent_idwhen the unit is a varianttitle,brand, and a shortdescriptionper language you actually searchattributesas{ code, value_id, label }priceandcurrencyof the unitin_stockandbackorderas booleans derived from the catalog stock recordcategory_idsupdated_at
Do not index a display string that already contains a currency symbol as the price. Keep the number and the currency.
Query
- Normalize the query.
- If the normalized query equals a SKU or GTIN, return that unit first.
- Otherwise run a text query across title, brand, attribute labels, and description, with title weighted above description.
- Apply selected facets as filters, not as optional boosts. A shopper who chose "blue" should not see red.
- Apply stock policy. Hide out-of-stock units when the shop is configured to hide them. Demote them when the shop still wants them visible.
- Page with a stable sort. Add
unit_idas a tiebreaker so a page boundary does not shuffle.
Facets
- Compute facet counts from the current text query and the other selected facets. Do not compute counts from the unfiltered catalog if the UI shows them next to a filtered result set.
- A facet value with a zero count may be hidden. Do not let the shopper select a value that would empty the result unless you explain that.
- Multi-select inside one facet is usually OR. Across facets it is AND. Say which one the UI implements and make the query match it.
- Price facets use the unit price in the shopper's display currency only after conversion. The filter still has to be reproducible from stored prices.
Multilingual and RTL
- Use a language-specific analyzer. Do not stem Persian with an English stemmer, and do not stem English with a Persian stemmer.
- Store
title_faandtitle_en(or one field per language you support) rather than one mixed field. - Detect the query language only as a hint. If the shopper is browsing the Persian catalog, search Persian fields first.
- Normalize Arabic Yeh
يto Persian Yehی, Arabic Kafكto Persian Kafک, Persian and Arabic-Indic digits to ASCII, and remove ZWNJ for matching soمیرومmatchesمیروم. Keep ZWNJ in the source catalog text. The normalizer does this. - Strip bidi marks from indexed and query text. They arrive from copied titles and should not change a match.
- RTL affects rendering of the search UI, not the score. Use the Persian and RTL skill for layout.
Ranking factors
Use these as a starting point, then change them when labeled queries show a miss:
- Exact SKU or GTIN match outranks a fuzzy title match.
- Title matches outrank description-only matches.
- An in-stock purchasable unit outranks an out-of-stock unit when both match.
- A newer
updated_atcan break ties. It should not outrank a clearly better text match. - Sponsored placements are labeled as sponsored in the UI and are not mixed into the organic score silently.
Write the formula down in the service that serves results. A boost that exists only in an indexer config and not in review notes will be retuned by accident.
Gotchas
- Indexing the parent product shows one price and one stock figure for every variant. Shoppers then open a color that is not the price they saw.
- Updating a variant price without updating the document leaves search and the product page in conflict. Update the document in the same flow as the catalog write, or from an outbox.
- Synonyms belong in a managed list (
tee/t-shirt). Do not add a synonym because one query failed once. - Typo tolerance on short queries (two or three characters) matches unrelated brands. Tighten fuzziness for short strings and for SKU fields.
- Facet labels in Persian still need stable ids. Searching the translated label as if it were the id breaks when the translation changes.
Verification
- A SKU query returns that unit even if the title uses different digits or Yeh/Kaf forms.
- A color facet returns only units with that color's value id.
- Out-of-stock policy matches the shop setting on page 1 and on the next page.
- An English stemmer is not applied to a Persian title field.
- A sponsored unit is visibly marked and is not the only explanation for an organic ranking change.
Evaluation
Worked examples and the checks they must satisfy are in evals/tasks.json.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

