agentleFS
asgard-ai-platformasgard-ai-platform/skills/algo-ecom-search/SKILL.md

algo-ecom-search

Skill238 starsChanged 6 months agoMITView on GitHub

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'.

The file

We split this skill into the rules it gives an agent

1 rule. About 0 are common, 1 is distinctive, and 0 are very specific to this project.

  • ≈0

    Common · estimate

    Many files like this have a rule of this kind.

  • ≈1

    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
  1. Distinctive:

    A/B testing search is hard: Search changes affect all queries.

    line 83

≈ “Common” is an estimate: at least 1 in 5 of the 350,495 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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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

InputExpectedWhy
Category-only query ("shoes")Browse intent, show popularNot a specific product search
Brand misspellingFuzzy brand matching"Nikee" → "Nike"
Long-tail query ("blue cotton v-neck t-shirt men XL")Attribute parsing neededMultiple 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

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.