charlieviettq/awesome-agent-skill / .claude/skills/algo-ecom-search
"algo-ecom-search"
Verified"Optimize e-commerce search relevance across the full pipeline from query understanding to result presentation. Use this skill when the user needs to improve search quality, implement query processing features, or diagnose search relevance issues — even if they say 'search results are bad', 'improve product search', or 'search relevance optimization'.".
E-Commerce Search Relevance
Overview
E-commerce search is a pipeline: query understanding → retrieval → ranking → presentation. Each stage affects relevance. Optimization requires diagnosing WHICH stage fails, not just tuning one component. Zero-result rate, click-through rate, and add-to-cart rate are key metrics.
When to Use
Trigger conditions:
- Diagnosing why search results don't meet user expectations
- Implementing query processing features (spell check, synonyms, intent detection)
- Reducing zero-result searches and improving conversion
When NOT to use:
- For ranking algorithm design only (use e-commerce ranking skill)
- For text relevance scoring only (use BM25)
Algorithm
IRON LAW: Search Quality Is Determined by the WEAKEST Pipeline Stage
Query understanding, retrieval, ranking, and presentation are sequential.
Perfect ranking cannot fix bad retrieval (missing products). Perfect
retrieval cannot fix bad query understanding (wrong intent). Diagnose
which stage fails FIRST before optimizing.
Phase 1: Input Validation
Audit current search: sample 100 queries by volume. For each, evaluate: query understanding (correct intent?), retrieval (relevant products in candidate set?), ranking (best products at top?), presentation (useful display?). Gate: Weakness localized to specific pipeline stage(s).
Phase 2: Core Algorithm
Query understanding: 1. Spell correction (edit distance, n-gram). 2. Synonym expansion (earbuds↔earphones). 3. Intent classification (product search vs brand search vs category browse). 4. Query rewriting (attribute extraction: "red shoes size 10" → color:red, category:shoes, size:10).
Retrieval optimization: 1. Multi-field search (title, description, brand, category, SKU). 2. Boosting strategies (title match > description match). 3. Filter vs boost (hard constraints: category, availability vs soft signals: popularity).
Result quality: 1. Zero-result fallback (relax query, suggest alternatives). 2. Faceted navigation (filters by price, brand, rating). 3. Did-you-mean suggestions.
Phase 3: Verification
Measure: zero-result rate (<5% target), CTR on first page (>30% target), NDCG on judged queries. Gate: Key metrics improve over baseline.
Phase 4: Output
Return search audit with prioritized improvements.
Output Format
{
"audit": {"zero_result_rate": 0.08, "avg_ctr": 0.25, "top_failing_queries": ["earbuds wireless", "gift ideas"]},
"recommendations": [{"stage": "query_understanding", "issue": "no_synonym_expansion", "impact": "high", "fix": "Add earbuds↔earphones synonym"}],
"metadata": {"queries_sampled": 100, "period": "2025-Q1"}
}
Examples
Sample I/O
Input: "wireles earbud" (misspelled) returns 0 results Expected: Spell correction → "wireless earbuds" → relevant products displayed. Recommendation: implement spell correction.
Edge Cases
| Input | Expected | Why |
|---|---|---|
| Category-only query ("shoes") | Browse intent, show popular | Not a specific product search |
| Brand misspelling | Fuzzy brand matching | "Nikee" → "Nike" |
| Long-tail query ("blue cotton v-neck t-shirt men XL") | Attribute parsing needed | Multiple structured attributes in free text |
Gotchas
- Synonym maintenance: Synonym lists need ongoing curation. "AirPods" is a brand, not a synonym for "earbuds." Wrong synonyms hurt precision.
- Over-recall: Aggressive synonym expansion and fuzzy matching return too many irrelevant results. Balance recall (find everything) with precision (only relevant).
- Language-specific challenges: Chinese search needs word segmentation. "皮鞋" (leather shoes) should not match "拖鞋" (slippers) despite shared "鞋".
- Search analytics are essential: Without tracking query-level CTR, zero-result queries, and conversion rates, you're optimizing blind.
- A/B testing search is hard: Search changes affect all queries. Some improve, some regress. Measure aggregate metrics AND stratify by query type.
References
- For query understanding pipeline architecture, see
references/query-pipeline.md - For search relevance evaluation methodology, see
references/relevance-evaluation.md
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| writing-skillsobra/superpowersUse when creating new skills, editing existing skills, or verifying skills work before deployment | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| xlsxanthropics/skillsUse this skill any time a spreadsheet file is the primary input or output. This means any task where the user wants to: open, read, edit, or fix an existing .xlsx, .xlsm, .xltx, .csv, or .tsv file (e.g., adding columns, computing formulas, formatting, charting, cleaning messy data); create a new spreadsheet from scratch or from other data sources; or convert between tabular file formats. Trigger especially when the user references a spreadsheet file by name or path — even casually (like "the xlsx in my downloads") — and wants something done to it or produced from it. Also trigger for cleaning or restructuring messy tabular data files (malformed rows, misplaced headers, junk data) into proper spreadsheets. The deliverable must be a spreadsheet file. Do NOT trigger when the primary deliverable is a Word document, HTML report, standalone Python script, database pipeline, or Google Sheets API integration, even if tabular data is involved. | Stars: 198k | Updated | Claude CodeCodex | Verified | Install |
| shipping-and-launchaddyosmani/agent-skillsPrepares production launches. Use when preparing to deploy to production, or when asking what needs to be in place before shipping. Use when you need a pre-launch checklist, when setting up monitoring, when planning a staged rollout, or when you need a rollback strategy. | Stars: 119k | Updated | Claude CodeCodex | Verified | Install |
| childhoodthedotmack/claude-memBabysit a shipped release after merge, publication, or deployment. Verify published packages, production behavior, installed plugins, and late CI or user reports until the observation window is clean; use babysit for PR readiness before release. | Stars: 118k | Updated | Claude CodeCodex | Verified | Install |