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 that clearly communicates the hybrid search niche and provides explicit 'Use when' triggers covering multiple relevant scenarios. Its main weakness is that the 'what' portion is somewhat high-level — it could benefit from listing more specific concrete actions beyond 'combine vector and keyword search'. Overall it performs well for skill selection purposes.
Suggestions
Add 2-3 more specific concrete actions to improve specificity, 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 but suffers severely from poor token efficiency and lack of progressive disclosure. Over 400 lines of inline code makes this a monolithic reference document rather than a concise, well-structured skill. The content would benefit enormously from splitting templates into separate files and keeping only the core RRF pattern and architecture overview in the main SKILL.md.
Suggestions
Extract Templates 2-4 (PostgreSQL, Elasticsearch, RAG Pipeline) into separate referenced files (e.g., postgres_hybrid.md, elasticsearch_hybrid.md, rag_pipeline.md) and link to them from a concise overview.
Remove the 'When to Use This Skill' section and the 'Core Concepts' architecture diagram — Claude already understands hybrid search concepts; jump straight to the fusion methods table and RRF implementation.
Add explicit validation/error handling guidance: what to check when searches return empty results, how to verify fusion is working correctly, and how to diagnose when one search method dominates.
Trim the Best Practices section to just the most non-obvious points — 'Log both scores' and 'Tune weights empirically' are the only ones that add real value.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~400+ lines, with four large template implementations that are largely boilerplate code. The 'When to Use This Skill' and 'Core Concepts' sections explain things Claude already knows. The Elasticsearch and PostgreSQL templates could be dramatically condensed or split into separate files. | 1 / 3 |
Actionability | All four templates provide fully executable, copy-paste ready Python code with proper type hints, docstrings, and complete implementations. The code covers RRF, linear combination, PostgreSQL, Elasticsearch, and a custom RAG pipeline with concrete, working examples. | 3 / 3 |
Workflow Clarity | The HybridRAGPipeline (Template 4) shows a clear multi-step pipeline (embed → search → fuse → rerank), but there are no validation checkpoints, error handling, or feedback loops for when searches fail or return empty results. The steps are implicit in code rather than explicitly documented. | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of code with no bundle files to offload detailed templates. All four large templates are inline when they should be in separate referenced files. The SKILL.md should be an overview with the RRF function and links to template files for PostgreSQL, Elasticsearch, and RAG pipeline implementations. | 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
b09ec7f
- 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.