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
93%
1.13xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./tests/ext_conformance/artifacts/agents-wshobson/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 identifies the hybrid search niche and provides explicit 'Use when' guidance. The main weakness is that the 'what' portion could be more specific about concrete actions beyond just 'combine.'
Suggestions
Add more specific concrete actions to improve specificity, e.g., 'Combine vector and keyword search with score fusion, reranking, and index configuration for improved retrieval.'
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (hybrid search combining vector and keyword) and a general action ('combine'), but doesn't list multiple concrete actions like indexing, ranking, reranking, or specific implementation steps. | 2 / 3 |
Completeness | Clearly answers both what ('Combine vector and keyword search for improved retrieval') and when ('Use 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', 'retrieval', 'recall' — these are terms users would naturally use when seeking this capability. | 3 / 3 |
Distinctiveness Conflict Risk | The combination of 'vector and keyword search' with 'hybrid' retrieval creates a clear niche distinct from pure vector search skills, pure keyword 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 across multiple backends, demonstrating strong actionability. However, it is severely over-long and monolithic—most of the code could be in referenced files with the SKILL.md providing only the core RRF pattern and pointers. It also lacks validation steps and error handling guidance for what are complex, multi-step search operations.
Suggestions
Extract Templates 2-4 (PostgreSQL, Elasticsearch, Custom Pipeline) into separate referenced files, keeping only Template 1 (RRF) and a brief overview in SKILL.md
Remove the 'When to Use This Skill' and 'Core Concepts' sections—Claude already understands hybrid search concepts; replace with a one-line summary
Add validation/verification steps: how to evaluate search quality (e.g., check result relevance, measure MRR/recall), and error handling for empty results or failed searches
Trim the do's/don'ts to only non-obvious, domain-specific guidance rather than general best practices
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~400+ lines, with four large template implementations covering PostgreSQL, Elasticsearch, and a custom RAG pipeline. Much of this is boilerplate code that Claude could generate from brief specifications. The 'When to Use This Skill' and 'Core Concepts' sections explain things Claude already knows. The do's/don'ts section states obvious best practices. | 1 / 3 |
Actionability | The code templates are fully executable with proper type hints, imports, and complete implementations. The PostgreSQL, Elasticsearch, and pure Python examples are copy-paste ready with concrete SQL queries, API calls, and data structures. | 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 poor results or fail. No guidance on verifying search quality or handling edge cases beyond a brief mention in don'ts. | 2 / 3 |
Progressive Disclosure | All four templates are inlined in a single monolithic file with no bundle files or references to separate detailed documents. The PostgreSQL, Elasticsearch, and custom pipeline templates could each be separate files referenced from a concise overview. The result is a wall of code that's hard to navigate. | 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 (571 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- Dicklesworthstone/pi_agent_rust
- Commit
bbc5ade
- 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.