CtrlK
BlogDocsLog inGet started
Tessl Logo
SkillPublic

similarity-search-patterns

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

Quality

69%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide
SecuritybySnyk

Passed

No findings from the security scan

Fix and improve this skill with Tessl

tessl review fix ./plugins/llm-application-dev/skills/similarity-search-patterns/SKILL.md
SKILL.md
Quality
Evals
Security

Quality

Content

43%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 well structured as an overview with excellent progressive disclosure — a single, real, one-level-deep reference file clearly signaled and appropriately loaded with the concrete templates. But as a standalone document it is not actionable (no code, commands, or values) and contains no decision workflow, while its largest section re-teaches concepts Claude already knows and ships a malformed table row.

Suggestions

Add a minimal runnable snippet or a concrete decision rule to the body (e.g., one short pgvector or FAISS query example, or 'choose index by N: <10k Flat, <10M HNSW, >10M IVF+PQ with nprobe values') so the skill is actionable without opening the reference.

Convert the implicit best-practices ordering into an explicit numbered workflow (choose metric → start Flat → measure recall/latency → scale index → tune ef_search/nprobe → re-measure) with an explicit validation checkpoint after each change.

Cut the distance-metrics formula table (Claude knows cosine/Euclidean/dot-product) and fix the malformed Manhattan (L1) table row; spend the saved tokens naming which template in references/details.md fits which vector database.

DimensionReasoningScore

Conciseness

The body is short and free of prose padding, but the 'Core Concepts' section spends roughly half the body re-teaching things Claude already knows — the distance-metric table spells out "Cosine: 1 - (A·B)/(‖A‖‖B‖)" and "Euclidean (L2): √Σ(a-b)²", and the ASCII index-type box restates basic Flat/HNSW/IVF+PQ tradeoffs. This matches 'mostly efficient but includes some unnecessary explanation or could be tightened'; it is above anchor 2 because there is no padded narrative prose, and below anchor 4 because the whole metrics-formula table could be cut without loss.

3 / 5

Actionability

The body contains no code, commands, or parameter values — the best-practices bullets are high-level hints ("Tune parameters - ef_search, nprobe for recall/speed", "Pre-filter when possible") with nothing executable, and the broken Manhattan (L1) table row renders the one structured reference malformed. This matches anchor 2 ('minimal concrete guidance; high-level hints but missing the specific steps to execute'); it is above anchor 1 because specific tool names and parameter names are given, and below anchor 3/4 because all concrete, executable material is deferred to references/details.md, leaving the body itself unable to drive any implementation.

2 / 5

Workflow Clarity

There is no sequence anywhere in the body — sections are a static catalog (When to Use, Core Concepts, Best Practices) with no decision flow such as 'choose a metric → pick an index starting Flat → tune → measure recall', and no validation guidance beyond the bare injunction "Don't skip evaluation - Measure before optimizing". This matches anchor 2's 'rough sequence present but many gaps; steps poorly defined; validation absent' — the Don'ts hint at an ordering without ever stating it. It is above anchor 1 because the section structure and do/don't lists do imply a rough evaluation-then-optimize shape, and below anchor 3 because no actual steps are listed, let alone checkpoints.

2 / 5

Progressive Disclosure

Scored against the actual bundle: references/details.md exists (494 lines, four worked templates: Pinecone, Qdrant, pgvector/PostgreSQL, Weaviate), is exactly one level deep with no nested references inside it, and is clearly signaled by the dedicated section "Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates." The body keeps overview material in SKILL.md and splits all templates out, matching anchor 5's 'clear overview with well-signaled one-level-deep references; content appropriately split'.

5 / 5

Total

12

/

20

Passed

Description

78%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 description with an explicit two-part structure: a concise 'what' and a concrete 'Use when...' trigger list using natural domain vocabulary. The main gaps are modest — the 'what' clause names only one action rather than enumerating the skill's capabilities, and it omits high-frequency synonyms like RAG, embeddings, or vector search that users commonly say.

DimensionReasoningScore

Specificity

The description names the domain ("vector databases") and one concrete action ("Implement efficient similarity search"), but stops there — it never enumerates what the skill actually covers (index selection, parameter tuning, hybrid search), matching the 'names domain and 1-2 concrete actions' anchor. It is below anchor 4 because 'Lists several specific actions' does not hold: there is a single verb with no gaps-level enumeration, and above anchor 2 because the domain and action are concrete rather than generic.

3 / 5

Completeness

It explicitly answers both questions: the 'what' is "Implement efficient similarity search with vector databases" and the 'when' is an explicit "Use when..." clause listing three concrete trigger conditions. This matches anchor 5 ('clearly and explicitly answers both what AND when with concrete trigger phrases'); it is above anchor 4 because the 'when' is not merely present but enumerates multiple specific triggers rather than needing more specificity.

5 / 5

Trigger Term Quality

Natural trigger phrases are present — "building semantic search", "implementing nearest neighbor queries", "optimizing retrieval performance", "vector databases" — which users in this domain would actually say. It falls short of anchor 5's 'comprehensive coverage of natural terms including synonyms' because common variations users say are missing, e.g. RAG, embeddings, vector search, ANN, or product names like Pinecone/Qdrant/pgvector.

4 / 5

Distinctiveness Conflict Risk

The vector-database/similarity-search niche is well defined with distinct triggers ("nearest neighbor queries", "semantic search"), so it is 'mostly distinct; minor overlap risk with closely related skills' — a generic embeddings or RAG-orchestration skill could plausibly claim the same triggers. It is not anchor 5 because 'semantic search' and 'retrieval performance' are broad enough that a dedicated RAG-retrieval skill would compete for the same invocations.

4 / 5

Total

16

/

20

Passed

Validation

100%

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

Path

plugins/llm-application-dev/skills/similarity-search-patterns/SKILL.md

Reviewed

Table of Contents

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.