hybrid-search-implementation

Use it when:: Pure vector search misses exact terms like names or codes, and you want keyword matching too.
It does:: Runs vector and keyword search in parallel and fuses their rankings into one result list.
You get:: A design and, in its reference file, templates; it names fusion methods and when each fits.
Fusion methods:: Reciprocal Rank Fusion for general use, a weighted linear sum for tunable balance, a cross-encoder rerank for quality, cascade filtering for efficiency.

TL;DR

A short reference for hybrid retrieval, combining semantic vector search with keyword search so a query gets both meaning and exact matches. The SKILL.md diagrams the flow — the query fans out to a vector search and a keyword search, whose candidates are fused — and tabulates four fusion methods: Reciprocal Rank Fusion (general purpose, works without tuning), a weighted linear sum of scores (tunable), a cross-encoder reranker (highest quality) and a cascade that filters then reranks. Its advice: tune weights on your own data, start with RRF, add reranking for a quality jump, log both scores for debugging, A/B test real impact, and handle edge cases like empty results and single-word queries without over-fetching. The templates and worked examples are in a reference file.

Summarizes the skill at 4bde316.

npx skills add https://github.com/wshobson/agents --skill hybrid-search-implementation

skills.sh page Source on GitHub All skills from wshobson/agents

Total Downloads: 11,200 on skills.sh, Nov 9, 2026
Repo stars: 42,334 wshobson/agents
First seen: Jan 20, 2026 on skills.sh

Weekly Downloads

166

-12% over the 8 weeks to Nov 9

Weekly values

Week to	Installs
Sep 21	188
Sep 28	218
Oct 5	281
Oct 12	220
Oct 19	191
Oct 26	189
Nov 2	179
Nov 9	166

Category	category:agents category:software-engineering Build agents, orchestrate workers and give agents memory. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills.
Type	type:guidelines Knowledge and rules the agent applies while it works: best practices, design principles, API references.
Effect	effect:none Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code.
Needs	needs:none Instructions only. Works in any agent that supports skills.
Publisher	by:community Everyone else. Unverified vendor claims default to community.
Topics	databases agent-development

SKILL.md

From wshobson/agents at 4bde316. Checked daily, last changed Nov 6, 2026.

Frontmatter

name: hybrid-search-implementation
description: Combine vector and keyword search for improved retrieval. Use when implementing RAG systems, building search engines, or when neither approach alone provides sufficient recall.

Hybrid Search Implementation

Patterns for combining vector similarity and keyword-based search.

When to Use This Skill

Building RAG systems with improved recall
Combining semantic understanding with exact matching
Handling queries with specific terms (names, codes)
Improving search for domain-specific vocabulary
When pure vector search misses keyword matches

Core Concepts

1. Hybrid Search Architecture

Query → ┬─► Vector Search ──► Candidates ─┐
        │                                  │
        └─► Keyword Search ─► Candidates ─┴─► Fusion ─► Results

2. Fusion Methods

Method	Description	Best For
RRF	Reciprocal Rank Fusion	General purpose
Linear	Weighted sum of scores	Tunable balance
Cross-encoder	Rerank with neural model	Highest quality
Cascade	Filter then rerank	Efficiency

Templates and detailed worked examples

Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates.

Best Practices

Do's

Tune weights empirically - Test on your data
Use RRF for simplicity - Works well without tuning
Add reranking - Significant quality improvement
Log both scores - Helps with debugging
A/B test - Measure real user impact

Don'ts

Don't assume one size fits all - Different queries need different weights
Don't skip keyword search - Handles exact matches better
Don't over-fetch - Balance recall vs latency
Don't ignore edge cases - Empty results, single word queries