similarity-search-patterns

Implement efficient similarity search with vector databases. Use when building semantic search, implementing nearest neighbor queries, or optimizing retrieval performance.

1.09x

Quality

—

Does it follow best practices?

Impact

100%

1.09x

Average score across 3 eval scenarios

Securityby

Passed

No known issues

Quality

Content

65%

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

A highly actionable body with four complete, executable vector-store implementations, but it is token-heavy: it explains concepts Claude already knows and inlines ~400 lines of vendor code that would be better split into reference files. Workflow clarity is also limited because batch and destructive operations lack validation checkpoints.

Suggestions

Remove or shrink the 'Core Concepts' section (distance metrics, index-types diagram) — this is knowledge Claude already has — and let the templates carry the value.

Split each vendor implementation into its own reference file (e.g. references/pinecone.py, references/qdrant.py) and keep SKILL.md as a concise overview with one-level-deep links, improving both conciseness and progressive disclosure.

Add validation/confirmation guidance to the batch upsert and destructive delete/delete_by_filter paths (e.g. verify counts, confirm filter scope before deletion) to raise workflow clarity.

Dimension	Reasoning	Score
Conciseness	The four full vendor implementations are actionable, but the 'Core Concepts' section explains distance metrics and index types Claude already knows, and ~400 lines of inline code could be tightened or split, matching the 'mostly efficient but includes unnecessary explanation' anchor.	2 / 3
Actionability	Four complete, import-bearing, executable Python class implementations (Pinecone, Qdrant, pgvector, Weaviate) with real API calls are copy-paste ready, matching the fully-executable anchor.	3 / 3
Workflow Clarity	The skill presents standalone patterns rather than a sequenced workflow, and batch upsert plus destructive delete/delete_by_filter methods carry no validation or confirmation, which caps workflow clarity at 2 per the batch/destructive guideline.	2 / 3
Progressive Disclosure	No references/scripts/assets bundle exists, and four full vendor implementations sit inline in SKILL.md when they could be split into separate reference files; sections are organized but content that should be separate is inline.	2 / 3
	Total	9 / 12 Passed

Description

90%

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 clear, third-person description with an explicit 'Use when' trigger clause and natural, distinctive trigger terms. Its only weakness is specificity: it states a single high-level capability rather than enumerating the concrete actions the skill actually supports.

Suggestions

Expand the capability clause to list several concrete actions, e.g. '...vector databases — upsert and query embeddings, build HNSW/IVF indexes, and combine vector with keyword (hybrid) search.'

Consider adding 'embeddings' or 'RAG retrieval' as additional natural trigger terms users commonly say.

Dimension	Reasoning	Score
Specificity	The description names the domain and one concrete action ('Implement efficient similarity search with vector databases') but does not enumerate multiple distinct capabilities such as upsert, query, indexing, or hybrid search, which appear only in the body.	2 / 3
Completeness	It explicitly answers 'what' ('Implement efficient similarity search with vector databases') and 'when' via a dedicated 'Use when ...' trigger clause, satisfying both halves.	3 / 3
Trigger Term Quality	Phrases like 'building semantic search', 'implementing nearest neighbor queries', and 'optimizing retrieval performance' are natural terms a user would say when they need this skill, giving good coverage.	3 / 3
Distinctiveness Conflict Risk	The vector-database similarity-search niche with terms like 'semantic search' and 'nearest neighbor' is distinct and unlikely to trigger for unrelated skills.	3 / 3
	Total	11 / 12 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
skill_md_line_count	SKILL.md is long (561 lines); consider splitting into references/ and linking	Warning

	Total	15 / 16 Passed

Repository: Dicklesworthstone/pi_agent_rust
Commit: e9f9b67

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