hybrid-search-implementation
🎯SkillA guide to building search that mixes meaning-based search with plain keyword search to find better results. It helps when you build a search engine or an AI that answers questions from your own documents.
Installation
npx skills add wshobson/agents --skill hybrid-search-implementationRun it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).
Uses skills.sh · Node.js 22.20+
After installing
Ask for related work and the agent uses it on its own, or call it yourself.
/hybrid-search-implementationInstall by hand
Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.
Open the skill folder →- This project
.claude/skills/hybrid-search-implementation/ - All projects
~/.claude/skills/hybrid-search-implementation/
These paths are for Claude Code. For other tools, the command above puts it in the right place.
What this skill does
Overview
This skill shows how to build hybrid search. Hybrid search runs two searches at once and merges the results. One is vector search, which finds text with similar meaning. The other is keyword search, which finds exact words.
Key Features
- Combine meaning-based and keyword results into one ranked list.
- Pick a merge method, such as RRF, which blends rankings without much tuning.
- Add reranking, where a second model reorders the top results for better quality.
- Catch exact terms like names and codes that meaning-based search often misses.
- Follow tips on tuning, logging scores and testing with real users.
Who is this for?
This is for developers building search features or RAG systems. RAG means an AI looks up your documents before it answers. It is most useful when search alone keeps missing important results.
Summarized by AI from this skill's SKILL.md. Suggest a better one
SKILL.md
View on GitHub →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
More from this repository10
Helps you build a consistent look for your app with Tailwind CSS v4. It sets up shared colors, sizes, dark mode and reusable components so every screen matches.
A guide to TypeScript's advanced type features, which describe the shape of your data so mistakes are caught before the code runs. It covers reusable types, types that change based on rules, and built-in helper types, with short examples.
Guidance for building reliable server-side apps with Node.js, using Express or Fastify. It covers login, error handling, databases, API design and a list of proven best practices.
Intelligent automation and multi-agent orchestration for Claude Code
Claude Code plugin for AI-powered framework migration workflows, coordinating specialized agents to plan and execute transitions between technology stacks as part of the wshobson/agents marketplace.
A Claude Code plugin for payment system integration covering Stripe, PayPal, and billing platforms with checkout flows, subscription management, and webhook handling in the wshobson/agents ecosystem.
A Claude Code plugin bundling core development tools and agents for everyday tasks like debugging and code generation, part of the wshobson/agents marketplace with 73 focused plugins.
Claude Code plugin for observability and monitoring including logging, metrics, distributed tracing, and alerting, part of the wshobson/agents marketplace with 73 focused plugins.
A Claude Code plugin providing specialized AI agents for deployment strategy planning and execution, covering blue-green deployments, canary releases, rolling updates, and zero-downtime patterns.
Claude Code plugin for JVM language development including Java, Kotlin, and Scala with specialized agents for idiomatic patterns, build tools, and runtime optimization in the wshobson/agents marketplace.