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 communicates the hybrid search niche and provides explicit 'Use when' guidance. The main weakness is that the capability description could be more specific about concrete actions beyond the high-level 'combine vector and keyword search.'
Suggestions
Add more specific concrete actions, 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 ('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', 'recall' — these are terms users would naturally use when seeking this capability. | 3 / 3 |
Distinctiveness Conflict Risk | The combination of 'vector and keyword search' hybrid approach is a clear niche. While it could partially overlap with a pure vector search or pure keyword search skill, the explicit hybrid framing and RAG context make it distinctly identifiable. | 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 bloated—all four templates are inlined creating a massive document that wastes context window. The content would benefit enormously from splitting templates into separate files and keeping only the core RRF pattern and a navigation overview in the main skill.
Suggestions
Move Templates 2-4 (PostgreSQL, Elasticsearch, Custom Pipeline) into separate referenced files (e.g., postgres_hybrid.md, elasticsearch_hybrid.md) and keep only Template 1 (RRF) inline as the core pattern.
Remove the 'When to Use This Skill' section and the 'Core Concepts' explanation—Claude already understands when hybrid search is appropriate and what fusion methods are.
Remove the generic Do's/Don'ts best practices list—these are common sense for Claude and waste tokens.
Add validation/verification guidance: how to evaluate hybrid search quality (e.g., compare recall@k between vector-only, keyword-only, and hybrid; log score distributions to detect issues).
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~400+ lines with four full template implementations. Much of this (Elasticsearch, PostgreSQL, custom pipeline) could be separate reference files. The 'When to Use This Skill' and 'Core Concepts' sections explain things Claude already knows. The do's/don'ts list is generic advice Claude doesn't need. | 1 / 3 |
Actionability | The code templates are fully executable with proper type hints, imports, and complete implementations. The RRF, linear combination, PostgreSQL, Elasticsearch, and custom pipeline templates are all copy-paste ready with clear function signatures and docstrings. | 3 / 3 |
Workflow Clarity | Template 4 (HybridRAGPipeline) shows a clear multi-step pipeline (embed → parallel search → fuse → rerank), but there are no validation checkpoints, error handling, or verification steps. For a search pipeline that could silently return poor results, missing validation caps this at 2. | 2 / 3 |
Progressive Disclosure | This is a monolithic wall of code with four large templates all inline. The PostgreSQL, Elasticsearch, and custom pipeline templates should be in separate reference files. The SKILL.md should be a concise overview with links to these detailed 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
47823e3
- 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.