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.

1.17x

Quality

66%

Does it follow best practices?

Impact

95%

1.17x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Optimize this skill with Tessl

npx tessl skill review --optimize ./plugins/llm-application-dev/skills/hybrid-search-implementation/SKILL.md

Quality

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 that clearly communicates the skill's purpose and when to use it. The 'Use when' clause with multiple trigger scenarios is well-constructed. The main weakness is that the 'what' portion 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 to the capability description, e.g., 'Combine vector and keyword search with score fusion, reranking, and weight tuning 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' retrieval creates a clear niche that is distinct from pure vector search skills, pure keyword/full-text search skills, or general RAG 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 across multiple backends, demonstrating strong actionability. However, it is severely over-long and monolithic—four complete implementations are inlined when one core template plus references would suffice. The lack of validation steps, error handling guidance, and progressive disclosure significantly reduces its effectiveness as a skill file.

Suggestions

Extract Templates 2-4 (PostgreSQL, Elasticsearch, Custom Pipeline) into separate referenced files, keeping only Template 1 (RRF) and a brief comparison table in the main SKILL.md

Remove the 'When to Use This Skill' and 'Core Concepts' sections—Claude already understands when hybrid search is appropriate and the basic architecture

Add explicit validation/error handling guidance: what to do when one search returns empty results, how to verify fusion quality, and how to handle score normalization edge cases

Add a concise 'Quick start' section at the top showing the minimal RRF implementation in ~15 lines before diving into full templates

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 files referenced from a concise overview. There's no navigation structure or signposting to help find the right template quickly.	1 / 3
	Total	7 / 12 Passed

Validation

90%

Warnings & errors only

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: 27a7ed9

Reviewed: 8 days ago

Table of Contents

Discovery Implementation Validation

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.