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 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 for a SKILL.md file, inlining ~400 lines of code that should be split into referenced files. It lacks validation checkpoints in workflows and explains concepts Claude already understands, wasting significant token budget.
Suggestions
Extract Templates 2-4 into separate referenced files (e.g., POSTGRES_HYBRID.md, ELASTICSEARCH_HYBRID.md, RAG_PIPELINE.md) and keep only Template 1 (RRF) plus a summary table in the main skill.
Remove the 'When to Use This Skill' and 'Core Concepts' sections—Claude already understands when hybrid search is useful and the basic architecture.
Add validation steps to the workflow: e.g., verify result counts, check score distributions, test with known queries to confirm both search paths return results.
Add a concise 'Quick Start' section at the top showing the minimal RRF pattern in ~15 lines, before any full templates.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | The skill is extremely verbose at ~400+ lines with four full template implementations. Much of this (Elasticsearch client wrapper, full PostgreSQL class, custom RAG pipeline) is boilerplate that Claude can generate on demand. The 'When to Use This Skill' and 'Core Concepts' sections explain things Claude already knows. The content would be far more effective as a concise reference of fusion methods with one compact example. | 1 / 3 |
Actionability | The code templates are fully executable with proper type hints, imports, and complete implementations. The PostgreSQL hybrid search includes schema setup, the Elasticsearch template includes index creation, and the RRF/linear combination functions are copy-paste ready. | 3 / 3 |
Workflow Clarity | Template 4 (HybridRAGPipeline) shows a clear multi-step pipeline (embed → parallel search → fuse → rerank), but there are no validation checkpoints, no error handling for failed searches, no guidance on verifying result quality, and no feedback loops for tuning weights. The 'Best Practices' section mentions tuning but doesn't provide a concrete process. | 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 referenced files. There's no clear overview-to-detail structure; the reader must scroll through hundreds of lines to find what they need. | 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
6e3d68c
- 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.