How to use the Hybrid Search Implementation agent skill

What is an agent skill and what does this one make the agent do?

An agent skill is a folder containing a SKILL.md file and optional supporting files that an AI agent can load when a task matches the skill's description. This one is for designing search that uses both vector similarity and keyword matching.

When installed, the agent can explain the hybrid search architecture, in which a query goes to both a vector search and a keyword search, and the candidates from each are merged in a fusion step. It can compare fusion methods: Reciprocal Rank Fusion (RRF) for general use, weighted linear scoring for tunable balance, cross-encoder reranking for highest quality, and cascade (filter then rerank) for efficiency. It can also point you to a reference file with concrete templates and worked examples.

• It provides guidance and templates; it does not run searches itself.
• It is intended for building a search system, not for searching your own files.

How do you install the Hybrid Search Implementation skill?

Download the ZIP for the skill from the page you are reading. Then choose one of two routes.

For Claude Code, unzip the download into your personal skills folder ~/.claude/skills/, or into a project's .claude/skills/ folder if you want the skill only for that project. The skill folder should contain SKILL.md and references/details.md.

In the Claude apps, open Settings, go to Capabilities, and upload the skill as a Skills entry.

How do you trigger the skill with a natural request?

You do not need to name the skill. The agent matches your request against the skill's description, which covers implementing RAG systems, building search engines, and cases where neither vector nor keyword search gives enough recall. Ask about the problem in your own words.

Name the concepts you care about, such as RRF, reranking or cross-encoder, so the agent knows which part of the guidance to use.

• "My RAG system misses documents when users search for exact product codes. How should I combine keyword and vector search?"
• "Should I use RRF or a weighted linear fusion for a search engine over legal documents with proper names?"
• "Give me a reciprocal rank fusion function in Python I can adapt."
• "What are the trade-offs between cross-encoder reranking and cascade filtering for low latency?"

What does a useful session look like?

Describe your data and constraints: the kind of queries users type, whether they include names or codes, how much latency you can accept, and which search engine or vector store you use. The skill's advice is generic, so the more specific your stack, the more useful the answer. Ask the agent to open the reference file when you want code, since the templates live there.

The reference file includes a Reciprocal Rank Fusion template in Python. Its function takes ranked lists of (doc_id, score) tuples, an optional constant k with a default of 60, and optional per-list weights, and returns a fused ranking. Treat it as a starting point to adapt and test.

What do you need before using it?

The source lists no required tools or packages for this skill. It runs no scripts and makes no network calls. Its contents are text and Python templates, so the only real prerequisite is a search problem to solve and a way to test the results against your own data.

The reference template is Python and uses only standard library typing and collections imports in the excerpt shown.

What are the safety notes?

The skill runs no scripts and uses no network access, according to its listing. Since it is guidance, the main risk is over-trusting it. The skill itself says its patterns must be tested on your data and stack before you rely on them.

Review any code the agent adapts before you run it in production, as you would with any code.

What tips make the advice work better?

Tune weights empirically on your own queries rather than trusting defaults. The skill suggests starting with RRF because it works without tuning, then adding reranking for a significant quality gain.

Log both the vector and keyword scores to help debugging, and A/B test changes to measure real user impact. Do not assume one weighting fits all queries, and do not skip keyword search, since it handles exact matches better.

Also plan for edge cases such as empty results and single-word queries.