postgres-hybrid-text-search

Use this skill to implement hybrid search combining BM25 keyword search with semantic vector search using Reciprocal Rank Fusion (RRF). **Trigger when user asks to:** - Combine keyword and semantic search - Implement hybrid search or multi-modal retrieval - Use BM25/pg_textsearch with pgvector together - Implement RRF (Reciprocal Rank Fusion) for search - Build search that handles both exact terms and meaning **Keywords:** hybrid search, BM25, pg_textsearch, RRF, reciprocal rank fusion, keyword search, full-text search, reranking, cross-encoder Covers: pg_textsearch BM25 index setup, parallel query patterns, client-side RRF fusion (Python/TypeScript), weighting strategies, and optional ML reranking.

Quality

87%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

Passed

No findings from the security scan

Quality

Content

82%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

A well-structured, highly actionable guide dominated by executable code across SQL, Python, and TypeScript with clear sequencing and verification guidance. Its main gaps are mild verbosity from version-sensitive prose and an all-inline structure that could split advanced topics into reference files.

Suggestions

Move time-sensitive version statements (pg_textsearch prerelease status, PostgreSQL 17/18 support) into a dedicated compatibility/deprecated section so they don't burden the main flow.

Extract the ML reranking and pgvectorscale scaling sections into separate reference files (e.g., references/reranking.md, references/scaling.md) with one-level-deep links from the body to improve progressive disclosure.

Add an explicit validation checkpoint after the Golden Path setup (e.g., run the Monitoring EXPLAIN steps before proceeding to query patterns) to make the workflow's verify step mandatory rather than optional.

Dimension	Reasoning	Score
Conciseness	Mostly efficient — dominated by executable code, tables, and direct guidance with little padding of concepts Claude already knows — but includes some introductory prose and time-sensitive version statements ('pg_textsearch is currently in prerelease... supports PostgreSQL 17 and 18') outside any deprecated section that could be trimmed.	4 / 5
Actionability	Provides fully executable, copy-paste-ready SQL, Python, and TypeScript across setup, RRF fusion, weighting, reranking, scaling, and debugging, covering the common cases concretely.	5 / 5
Workflow Clarity	Clear sequences are present (Golden Path setup, parallel-query-then-fuse, numbered rerank steps) with verification via the Monitoring section's EXPLAIN checks and a Common Issues troubleshooting table, though explicit validate-before-proceed checkpoints are implicit rather than enforced.	4 / 5
Progressive Disclosure	No bundle files exist; the single ~250-line body is organized into clear headed sections and delegates deep pgvector tuning and pgvectorscale details to external sibling skills/docs via signaled links, though some advanced sections (reranking, pgvectorscale scaling) could be split into separate reference files.	4 / 5
	Total	17 / 20 Passed

Description

92%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

A strong, specific description that clearly states both what the skill does and when to use it, with comprehensive trigger phrases. The only weakness is that parts of the keyword list lean technical rather than natural user language.

Dimension	Reasoning	Score
Specificity	Names multiple concrete actions — 'implement hybrid search combining BM25 keyword search with semantic vector search using Reciprocal Rank Fusion (RRF)' plus a 'Covers:' list (BM25 index setup, parallel query patterns, client-side RRF fusion, weighting, ML reranking), giving comprehensive coverage.	5 / 5
Completeness	Explicitly answers 'what' (implement hybrid search combining BM25 + vector via RRF) and 'when' via a 'Trigger when user asks to:' block with five concrete trigger phrases.	5 / 5
Trigger Term Quality	Good keyword coverage with natural phrases ('hybrid search', 'keyword search', 'semantic search', 'full-text search') and synonyms (RRF / reciprocal rank fusion), but several listed terms (pg_textsearch, cross-encoder) are technical jargon rather than terms a user would naturally say.	4 / 5
Distinctiveness Conflict Risk	Occupies a clear niche (PostgreSQL hybrid BM25+vector search with RRF via pg_textsearch+pgvector) with distinct triggers and minimal overlap; it deliberately contrasts with the sibling pgvector-semantic-search skill.	5 / 5
	Total	19 / 20 Passed

Validation

93%

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 — 15 / 16 Passed

Validation for skill structure

Criteria	Description	Result
metadata_version	'metadata.version' is missing	Warning

	Total	15 / 16 Passed

Repository: timescale/pg-aiguide
Path: skills/postgres-hybrid-text-search/SKILL.md
Commit: 2bf9f11

Reviewed: 3 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.