Combine vector and keyword search for improved retrieval

Hybrid search implementation

by wshobson · MIT license · ★ 39,857 on GitHub · updated Sep 21

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

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

Overview

Patterns for combining vector similarity and keyword-based search.

Manual install (npx, ZIP)

Claude Codenpx skills add wshobson/agents --skill hybrid-search-implementation -g -a claude-code

Claude Code (manual)

mkdir -p ~/.claude/skills && curl -sL https://codeload.github.com/wshobson/agents/tar.gz/4236bb91f839 \
  | tar -xz -C ~/.claude/skills --strip-components=4 agents-4236bb91f839/plugins/llm-application-dev/skills/hybrid-search-implementation

Windows (PowerShell)

New-Item -ItemType Directory -Force "$HOME\.claude\skills" | Out-Null; Invoke-WebRequest "https://m.agentalley.io/zip/4e6c58841fda563d973b/hybrid-search-implementation.zip" -OutFile "$env:TEMP\hybrid-search-implementation.zip"; Expand-Archive "$env:TEMP\hybrid-search-implementation.zip" -DestinationPath "$HOME\.claude\skills" -Force

Claude.ai / desktopDownload the ZIP and upload it under Settings → Capabilities → Skills.

Codex, Cursor, other agentsPoint them at SKILL.md. The other files are plain text.

Connects with Agent Alley MCP · agentalley.io/mcp

Files included

SKILL.md2.0 KB
references/1 file · 15.8 KB

Read the files here

wshobson/4236bb92 files

SKILL.md2.0 KB

SKILL.md

Show the full text57 lines

hybrid-search-implementation/SKILL.md57 lines · 2.0 KB

PreviewCode

Outline

RawView on GitHub

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

1	---
2	name: hybrid-search-implementation
3	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.
4	---
5
6	# Hybrid Search Implementation
7
8	Patterns for combining vector similarity and keyword-based search.
9
10	## When to Use This Skill
11
12	- Building RAG systems with improved recall
13	- Combining semantic understanding with exact matching
14	- Handling queries with specific terms (names, codes)
15	- Improving search for domain-specific vocabulary
16	- When pure vector search misses keyword matches
17
18	## Core Concepts
19
20	### 1. Hybrid Search Architecture
21
22	```
23	Query → ┬─► Vector Search ──► Candidates ─┐
24	│ │
25	└─► Keyword Search ─► Candidates ─┴─► Fusion ─► Results
26	```
27
28	### 2. Fusion Methods
29
30	\| Method \| Description \| Best For \|
31	\| ----------------- \| ------------------------ \| --------------- \|
32	\| RRF \| Reciprocal Rank Fusion \| General purpose \|
33	\| Linear \| Weighted sum of scores \| Tunable balance \|
34	\| Cross-encoder \| Rerank with neural model \| Highest quality \|
35	\| Cascade \| Filter then rerank \| Efficiency \|
36
37	## Templates and detailed worked examples
38
39	Full template library and detailed worked examples live in `references/details.md`. Read that file when you need the concrete templates.
40
41	## Best Practices
42
43	### Do's
44
45	- Tune weights empirically - Test on your data
46	- Use RRF for simplicity - Works well without tuning
47	- Add reranking - Significant quality improvement
48	- Log both scores - Helps with debugging
49	- A/B test - Measure real user impact
50
51	### Don'ts
52
53	- Don't assume one size fits all - Different queries need different weights
54	- Don't skip keyword search - Handles exact matches better
55	- Don't over-fetch - Balance recall vs latency
56	- Don't ignore edge cases - Empty results, single word queries
57