vector-product-search
Skill1 starsChanged 18 days agoMITView on GitHub
Add vector retrieval beside lexical product search, with one embedding per purchasable unit and exact SKU lookup kept first. Use when adding embedding search, hybrid ranking, or re-embedding after catalog edits.
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
- marketplace-search-and-rankingSkill
- 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
- woocommerce-plugin-developmentSkill
- woocommerce-rest-apiSkill
- wordpress-plugin-securitySkill
The file
We split this skill into the rules it gives an agent
6 rules. About 0 are common, 5 are distinctive, and 1 is 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.
1
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Distinctive: line 12
Use this skill when lexical search is not enough for paraphrased queries.
- Distinctive: line 14
Do not claim a recall or conversion number.
- Very specific: line 19
Use the same model, dimension, and similarity metric for indexing and querying.
- Distinctive: line 20
Keep price, stock, and facet ids as filter fields.
- Distinctive: line 47
Delete the vector when the unit is deleted.
- Distinctive: line 55
Do not log shopper queries next to identifiers you are not allowed to retain.
≈ “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
Vector product search
Use this skill when lexical search is not enough for paraphrased queries. Facets, stock, and lexical ranking stay in the marketplace search skill. This skill adds a vector index. It does not replace SKU and GTIN lookup.
Do not claim a recall or conversion number. Choose a model, record its id and dimension, and measure queries you have labeled.
Procedure
- Embed one text per purchasable unit. A variant with its own title or attributes gets its own vector. Copy the parent name into that text.
- Use the same model, dimension, and similarity metric for indexing and querying. Record
model_idand a hash of the embedded text on the document. - Keep price, stock, and facet ids as filter fields. Do not rely on the embedding to enforce "blue" or "in stock".
- Resolve an exact normalized SKU or GTIN before any vector query. If it hits one unit, return that unit first.
- Combine lexical and vector scores with a formula you write down. Re-embed when the text hash changes, not when only the price changes.
Normalization and hybrid scoring are in the index notes. Worked examples and checks are in evals/tasks.json.
What is embedded
Include the fields a shopper might paraphrase: title, brand, category names, and attribute labels. Run the same text normalization as lexical search, including Persian Yeh, Kaf, digits, and ZWNJ removal, before you embed.
Exclude price, stock counts, and SKUs from the embedded text. Price and stock change without the words changing, and a SKU is handled by exact match. If you later include them, the content hash must change when they change.
Query
- Normalize the query.
- Exact identifier match wins.
- Otherwise run the lexical query and the vector query with the same filters (facet ids, stock policy, category).
- Fuse the two ranked lists. A default you may start from is a weighted sum after each list is normalized to the same scale. Change the weight only when labeled queries say so.
- Page with a keyset on the fused score plus
unit_id.
Apply filters in both retrievals. A vector hit that ignores the selected color is a bug.
Re-embedding
- Store
model_id, dimension, metric (cosineunless the index documents another), andtext_hash. - A catalog write recomputes the hash. If the hash or the model id differs, enqueue that unit.
- Switching models rebuilds the index. Do not query an index with a different model than the one that wrote it.
- Delete the vector when the unit is deleted. A parent rebuild replaces that parent's vectors as a set.
Gotchas
- Embedding only the parent returns one vector for every size and color.
- Cosine and dot product are not interchangeable unless the vectors are normalized and you meant that equivalence.
- A vector score must not outrank an exact SKU match.
- Indexing the raw Persian string and querying the normalized string misses. Normalize both.
- Do not log shopper queries next to identifiers you are not allowed to retain. The query text can contain an address or a name the shopper pasted.
Verification
- A SKU query returns that unit even when a nearer vector belongs to another product.
- A color filter removes other colors from the vector results, not only from the lexical results.
- Changing the price does not change
text_hash. Changing the title does, and that unit is re-embedded. - Deleting a variant removes its vector.
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.

