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

65%

Does it follow best practices?

Impact

100%

1.09x

Average score across 3 eval scenarios

Securityby

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./tests/ext_conformance/artifacts/agents-wshobson/llm-application-dev/skills/similarity-search-patterns/SKILL.md

The canonical home for this skill is similarity-search-patterns in wshobson/agents

Quality

Content

61%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's strength is actionability — four complete, runnable implementations that cover the major vector databases. Its weaknesses are structural: a monolithic inline layout with no reference files, redundant explanation of known concepts, and no workflow sequencing or validation guidance for destructive/batch operations like bulk deletes and upserts.

Suggestions

Move each vendor implementation to a one-level-deep reference file (e.g. references/pinecone.md, references/qdrant.md) and keep only a decision table plus minimal quick-start in SKILL.md.

Remove or drastically compress the 'Core Concepts' distance-metric and index-type tables, which re-explain knowledge Claude already has.

Add a brief validation step for destructive and batch operations — e.g. dry-run counts before delete_by_filter, and recall measurement after index creation — to lift workflow clarity.

Dimension	Reasoning	Score
Conciseness	Mostly code with little padded prose, but the 'Core Concepts' section (distance-metrics table and ASCII index-type chart) explains concepts Claude already knows, and four full vendor client classes inline is more bulk than any single session needs. Not 2 because the prose itself is lean, not 4 because the known-concept explanations and template duplication should be trimmed.	3 / 5
Actionability	Four complete, executable, copy-paste-ready implementations (Pinecone, Qdrant, pgvector with hybrid SQL, Weaviate) covering the common production cases, with concrete parameters and batch logic — fully matches the anchor for executable guidance covering common cases.	5 / 5
Workflow Clarity	No sequenced workflow exists — the skill is a pattern catalog with an implicit create-index → upsert → search flow and no validation checkpoints. The destructive and batch operations (delete_by_filter, batch upserts) include no verification steps, which caps this dimension at 3 per the batch-operations rule.	3 / 5
Progressive Disclosure	No bundle files exist and everything is inlined in one ~560-line SKILL.md; roughly 400 lines of per-vendor implementation detail clearly belong in separate reference files (e.g. references/pinecone.md). Section headers exist, but content that should be split out is inline with no references at all, matching anchor 2 better than 3.	2 / 5
	Total	13 / 20 Passed

Description

70%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 solid description with an explicit 'Use when...' trigger clause and natural keywords, written in third person without fluff. Its main weakness is a thin 'what' — a single action statement rather than a concrete capability list — which limits specificity and completeness.

Suggestions

Enumerate concrete capabilities in the 'what' portion, e.g. 'Build vector indexes (HNSW, IVF), implement hybrid semantic + keyword search, and tune recall/latency'.

Add common user synonyms and trigger phrases such as 'RAG', 'embeddings', 'kNN', or 'vector search' to broaden natural keyword coverage.

Sharpen the 'when' clause to reduce overlap with generic RAG/retrieval skills, e.g. 'Use when choosing or implementing a vector database backend'.

Dimension	Reasoning	Score
Specificity	Names the domain ("similarity search with vector databases") and one concrete action ("implement efficient similarity search") but does not list several specific actions, matching the anchor for 1-2 concrete actions without comprehensive coverage.	3 / 5
Completeness	Explicitly answers both what ("Implement efficient similarity search with vector databases") and when ("Use when building semantic search, implementing nearest neighbor queries, or optimizing retrieval performance"). Falls short of 5 because the 'what' is a single action rather than a concrete list of capabilities.	4 / 5
Trigger Term Quality	Includes natural phrases users would say — "semantic search", "nearest neighbor queries", "retrieval performance" — but misses common variations like RAG, embeddings, kNN, or "vector search". Not 3 because coverage is genuinely good, not 5 because several natural synonyms are absent.	4 / 5
Distinctiveness Conflict Risk	Vector-database similarity search is a clear niche with distinct triggers, but it has minor overlap risk with generic RAG/embedding/retrieval skills that could claim the same 'retrieval performance' triggers.	4 / 5
	Total	15 / 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
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
Path: tests/ext_conformance/artifacts/agents-wshobson/llm-application-dev/skills/similarity-search-patterns/SKILL.md
Commit: a65ce00

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