pgvector-semantic-search

Use this skill for setting up vector similarity search with pgvector for AI/ML embeddings, RAG applications, or semantic search. **Trigger when user asks to:** - Store or search vector embeddings in PostgreSQL - Set up semantic search, similarity search, or nearest neighbor search - Create HNSW or IVFFlat indexes for vectors - Implement RAG (Retrieval Augmented Generation) with PostgreSQL - Optimize pgvector performance, recall, or memory usage - Use binary quantization for large vector datasets **Keywords:** pgvector, embeddings, semantic search, vector similarity, HNSW, IVFFlat, halfvec, cosine distance, nearest neighbor, RAG, LLM, AI search Covers: halfvec storage, HNSW index configuration (m, ef_construction, ef_search), quantization strategies, filtered search, bulk loading, and performance tuning.

Quality

90%

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

81%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.

The body is highly actionable with executable SQL throughout and a clear default path, but it is a dense single-file reference that leans on some unnecessary background explanation and lacks explicit validation feedback loops for batch/destructive operations. Splitting advanced sections into reference files and adding verify-step checkpoints would lift the weaker dimensions.

Suggestions

Add explicit validation checkpoints to bulk-loading and REINDEX workflows (e.g. confirm index build completed via pg_stat_progress_create_index and verify recall against an exact-search baseline before shipping).

Move the detailed IVFFlat, binary-quantization, and filtering sections into one-level-deep reference files (e.g. references/quantization.md, references/filtering.md) referenced from the main body to improve progressive disclosure.

Trim the opening semantic-search explanation and the quantization-rationale prose to background Claude already knows, keeping the focus on executable rules and code.

Dimension	Reasoning	Score
Conciseness	Mostly lean with executable code and tight tables, but the opening semantic-search explainer and a few explanatory sentences (e.g. quantization rationale) assume background Claude already has and could be trimmed.	4 / 5
Actionability	Fully executable, copy-paste-ready SQL for store, index, query, binary quantization with re-ranking, filtering, bulk loading, and monitoring — covering the common cases with concrete parameter values.	5 / 5
Workflow Clarity	Clear golden-path defaults, sequenced index-after-load guidance, and a symptom→fix table, but it lacks explicit validation checkpoints for batch/destructive operations (bulk load, REINDEX) such as verifying recall or index build success before proceeding.	4 / 5
Progressive Disclosure	No bundle files exist and the body is a monolithic ~340-line reference with all detail inlined; it is well-sectioned but content that could live in separate files (IVFFlat, quantization, filtering) is not split out, and external links are only sporadically signaled.	3 / 5
	Total	16 / 20 Passed

Description

100%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.

The description is exemplary: it clearly states what the skill does, provides explicit trigger guidance with natural user phrases, and includes a thorough keyword list. It is specific, complete, and distinctive. No suggestions for improvement.

Dimension	Reasoning	Score
Specificity	Lists multiple concrete actions — setting up vector similarity search with pgvector, configuring HNSW/IVFFlat indexes, binary quantization, RAG, performance tuning — covering the domain comprehensively.	5 / 5
Completeness	Explicitly states what it does (vector similarity search with pgvector for embeddings/RAG/semantic search) and provides a concrete 'Trigger when user asks to:' block with multiple when-clauses.	5 / 5
Trigger Term Quality	Rich keyword coverage with natural user phrases ('semantic search', 'nearest neighbor search', 'HNSW', 'RAG', 'cosine distance') plus a dedicated Keywords line including synonyms and operators.	5 / 5
Distinctiveness Conflict Risk	Narrow, well-defined niche (pgvector/PostgreSQL vector search) with distinct triggers and technical vocabulary that minimize overlap with unrelated skills.	5 / 5
	Total	20 / 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/pgvector-semantic-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.