hybrid-search-implementation
Combine vector and keyword search for improved retrieval. Use when implementing RAG systems, building search engines, or when neither approach alone provides sufficient recall.
76
66%
Does it follow best practices?
Impact
95%
1.17xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/llm-application-dev/skills/hybrid-search-implementation/SKILL.mdQuality
Discovery
89%Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.
This is a solid description with excellent completeness and trigger term coverage. It clearly communicates the hybrid search niche and provides explicit 'Use when' guidance with multiple trigger scenarios. The main weakness is that the capability description could be more specific about the concrete actions the skill enables beyond the high-level 'combine vector and keyword search.'
Suggestions
Add more specific concrete actions, e.g., 'Combine vector and keyword search using reciprocal rank fusion, BM25 scoring, and embedding similarity for improved retrieval.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (hybrid search combining vector and keyword) and the general action (improved retrieval), but doesn't list specific concrete actions like 'rerank results', 'configure BM25 weights', 'build embedding pipelines', etc. | 2 / 3 |
Completeness | Clearly answers both 'what' (combine vector and keyword search for improved retrieval) and 'when' (implementing RAG systems, building search engines, or when neither approach alone provides sufficient recall) with explicit trigger guidance. | 3 / 3 |
Trigger Term Quality | Includes strong natural trigger terms: 'vector search', 'keyword search', 'RAG systems', 'search engines', 'recall' — these are terms users would naturally use when seeking this capability. | 3 / 3 |
Distinctiveness Conflict Risk | The combination of 'vector and keyword search' plus 'hybrid search' creates a clear niche that is distinct from pure vector search skills, pure keyword/full-text search skills, or general RAG skills. Unlikely to conflict with other skills. | 3 / 3 |
Total | 11 / 12 Passed |
Implementation
42%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
The skill provides high-quality, executable code templates for hybrid search but suffers significantly from verbosity—four largely redundant implementations bloat the file when one or two with references would suffice. The lack of progressive disclosure means this consumes excessive context window space, and the workflow lacks explicit validation steps for a multi-step search pipeline where things can go wrong (empty results, score normalization edge cases).
Suggestions
Extract Templates 2-4 (PostgreSQL, Elasticsearch, Custom Pipeline) into separate referenced files, keeping only the RRF/linear fusion core and a brief overview of each approach in SKILL.md
Remove the 'When to Use This Skill' and 'Core Concepts' sections—Claude already understands when hybrid search is useful and the basic architecture
Add explicit validation steps: check for empty result sets before fusion, validate score normalization doesn't produce NaN, and handle the case where one search method returns no results
Add a navigation section linking to the extracted template files with one-line descriptions of when to use each
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~400+ lines, with four full template implementations that are largely redundant (PostgreSQL, Elasticsearch, and custom pipeline all demonstrate the same hybrid search concept). The 'When to Use This Skill' and 'Core Concepts' sections explain things Claude already knows. The ASCII diagram and fusion methods table add marginal value relative to their token cost. | 1 / 3 |
Actionability | The code templates are fully executable with proper type hints, imports, and complete implementations. The PostgreSQL, Elasticsearch, and custom pipeline templates are copy-paste ready with real SQL queries, proper API usage, and working fusion algorithms. | 3 / 3 |
Workflow Clarity | The HybridRAGPipeline (Template 4) shows a clear 4-step pipeline (embed → search → fuse → rerank), but there are no validation checkpoints, error handling, or feedback loops for when searches return empty results or scores are anomalous. The pipeline steps are implicit in code rather than explicitly documented. | 2 / 3 |
Progressive Disclosure | All four templates are inlined in a single monolithic file with no references to external files. The PostgreSQL, Elasticsearch, and custom pipeline templates could easily be separate reference files, with the SKILL.md providing just the RRF core concept and linking out. There's no navigation structure beyond sequential headers. | 1 / 3 |
Total | 7 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (565 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- wshobson/agents
- Commit
91fe43e
- Reviewed
Table of Contents
Is this your skill?
If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.