similarity-search-patterns

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

Quality

—

Does it follow best practices?

Impact

—

No eval scenarios have been run

Securityby

Passed

No known issues

Quality

Content

57%

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

The skill uses good progressive disclosure by offloading templates to a real one-level reference, but the body itself lacks executable examples and contains a broken table and decorative diagram that hurt actionability and conciseness.

Suggestions

Fix the malformed distance-metrics table (the Manhattan/L1 row is split across extra columns) so it renders correctly and conveys the formula and use case.

Add at least one small executable snippet in the body (e.g. a minimal HNSW or flat-search call) so the skill is actionable without opening the reference.

Replace the decorative ASCII index-type box with a compact table or a few lines of text to reduce token overhead.

Dimension	Reasoning	Score
Conciseness	The body is mostly compact tables and lists, but the decorative ASCII index-type box and a malformed distance-metrics table (the Manhattan row) add padding and could be tightened, keeping it short of the lean/every-token-earns-its-place anchor at 3.	2 / 3
Actionability	Do's/Don'ts and index complexity give some concrete guidance, but all executable code is deferred to references/details.md and no copy-paste example appears in the body, fitting the 'incomplete / missing key details' anchor rather than the fully executable one.	2 / 3
Workflow Clarity	Sections are organized (When to Use, Core Concepts, Best Practices) but there is no sequenced multi-step workflow with validation checkpoints, which is acceptable guidance rather than the explicit-feedback-loop anchor at 3.	2 / 3
Progressive Disclosure	The body is an overview that clearly signals a single one-level-deep reference ('Full template library and detailed worked examples live in references/details.md'), and that file exists, matching the well-signaled one-level-deep anchor.	3 / 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 strong, well-formed description with explicit trigger guidance and natural keyword coverage; its only weakness is that the capability statement is a single broad action rather than a list of concrete actions.

Dimension	Reasoning	Score
Specificity	Names the domain ('vector databases') and one broad action ('Implement efficient similarity search') but does not list multiple distinct concrete actions, matching the 'names domain and some actions' anchor rather than the multi-action anchor at 3.	2 / 3
Completeness	It states what it does ('Implement efficient similarity search with vector databases') and an explicit 'Use when...' trigger clause, answering both what and when as the 3-anchor requires.	3 / 3
Trigger Term Quality	Phrases like 'semantic search', 'nearest neighbor queries', and 'retrieval performance' are natural terms a user would say, giving good coverage rather than just one or two relevant keywords.	3 / 3
Distinctiveness Conflict Risk	Vector-database similarity search is a clear niche with distinct triggers (semantic search, nearest neighbor queries), making it unlikely to fire for unrelated skills.	3 / 3
	Total	11 / 12 Passed

Validation

100%

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

Validation for skill structure

No warnings or errors.

Repository: wshobson/agents
Commit: d7cf7dc

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