Hybrid Search Architect

Hybrid Search Architect

What this skill does

This skill designs a hybrid search pipeline that combines dense vector search (semantic similarity) with BM25 sparse search (keyword matching). Hybrid search outperforms either method alone on most retrieval benchmarks because vector search handles semantic meaning while BM25 handles exact keyword matches, product names, codes, and rare terms. This skill picks the right combination and fusion strategy for your use case.

How to use

Claude Code / Cline

Copy this file to .agents/skills/hybrid-search-architect/SKILL.md in your project root.

Then ask:

• "Use the Hybrid Search Architect to improve our RAG pipeline's retrieval."
• "Design a hybrid search system for our product documentation."

Provide:

• What you're searching (type of documents)
• What queries look like (keywords, natural language, codes/IDs)
• Your current search stack (Pinecone, Weaviate, Elasticsearch, pgvector, etc.)
• Latency requirements

Cursor / Codex

Describe your current retrieval setup and query patterns alongside these instructions.

The Prompt / Instructions for the Agent

Step 1 — Determine if hybrid search is needed

Query pattern	Pure vector	Pure BM25	Hybrid
Natural language questions	✓	—	✓
Exact product names / SKUs	—	✓	✓
Technical codes / IDs	—	✓	✓
Conceptual / semantic	✓	—	✓
Mixed (most real-world)	—	—	✓

Use hybrid search when: queries are mixed (some keyword, some semantic), documents contain both prose and structured data, or pure vector search misses obvious keyword matches.

Step 2 — Choose a stack

Option A: Weaviate (easiest hybrid, built-in)

# pip install weaviate-client
import weaviate
from weaviate.classes.query import HybridFusion

client = weaviate.connect_to_local()
collection = client.collections.get("Documents")

results = collection.query.hybrid(
    query="payment processing error",
    fusion_type=HybridFusion.RELATIVE_SCORE,  # or RANKED
    alpha=0.5,   # 0 = pure BM25, 1 = pure vector, 0.5 = balanced
    limit=10,
    return_metadata=["score", "explain_score"]
)