similarity-search-patterns
Implement efficient similarity search with vector databases. Use when building semantic search, implementing nearest neighbor queries, or optimizing retrieval performance.
66
48%
Does it follow best practices?
Impact
100%
1.38xAverage score across 3 eval scenarios
Passed
No known issues
Optimize this skill with Tessl
npx tessl skill review --optimize ./plugins/llm-application-dev/skills/similarity-search-patterns/SKILL.mdQuality
Discovery
67%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 competent with a clear 'Use when' clause and reasonable domain specificity around vector databases and similarity search. However, it could benefit from more concrete actions (e.g., configuring indexes, choosing distance metrics, managing embeddings) and broader trigger term coverage to capture common user vocabulary like 'embeddings', 'vector store', or specific tool names.
Suggestions
Add more concrete actions such as 'configure vector indexes, select distance metrics, store and query embeddings' to improve specificity.
Expand trigger terms to include common user vocabulary like 'embeddings', 'vector store', 'FAISS', 'Pinecone', 'ChromaDB', 'cosine similarity', or 'RAG retrieval'.
| Dimension | Reasoning | Score |
|---|---|---|
Specificity | Names the domain (vector databases, similarity search) and some actions (building semantic search, implementing nearest neighbor queries, optimizing retrieval performance), but doesn't list multiple concrete specific actions like indexing strategies, embedding storage, distance metric selection, or specific database integrations. | 2 / 3 |
Completeness | Clearly answers both 'what' (implement efficient similarity search with vector databases) and 'when' (explicit 'Use when' clause covering semantic search, nearest neighbor queries, and retrieval performance optimization). | 3 / 3 |
Trigger Term Quality | Includes some relevant keywords like 'similarity search', 'vector databases', 'semantic search', 'nearest neighbor', and 'retrieval performance', but misses common user terms like 'embeddings', 'vector store', 'FAISS', 'Pinecone', 'ChromaDB', 'ANN', 'cosine similarity', or 'RAG'. | 2 / 3 |
Distinctiveness Conflict Risk | The terms 'semantic search' and 'retrieval performance' could overlap with general search/information retrieval skills or RAG pipeline skills. The vector database focus provides some distinction, but 'optimizing retrieval performance' is broad enough to conflict with other skills. | 2 / 3 |
Total | 9 / 12 Passed |
Implementation
29%Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.
This skill is essentially a code dump of four vector database client wrappers with minimal guidance on when to use each, no workflow for building a similarity search system, and no progressive disclosure. While the code itself is high-quality and executable, the skill fails as instructional content because it's excessively verbose with information Claude already knows (distance metrics, index types) and lacks the decision-making guidance and validation steps that would make it truly useful.
Suggestions
Drastically reduce content: keep a concise decision matrix for choosing a vector DB and index type, then reference separate files (e.g., PINECONE.md, QDRANT.md) for full implementations.
Add a clear end-to-end workflow: embed → index → search → evaluate recall → tune parameters, with explicit validation checkpoints at each stage.
Remove the Core Concepts section (distance metrics, index types) — Claude already knows these. Replace with project-specific gotchas and non-obvious configuration tips.
Add verification steps such as how to measure recall, validate index creation succeeded, and confirm search quality before deploying.
| Dimension | Reasoning | Score |
|---|---|---|
Conciseness | Extremely verbose at ~400+ lines with four full vector database implementations. Much of this is boilerplate code Claude could generate on its own. The distance metrics table, index types diagram, and conceptual explanations are things Claude already knows. This could be reduced to key patterns and gotchas rather than full class implementations. | 1 / 3 |
Actionability | The code templates are fully executable with proper imports, type hints, and complete class implementations for Pinecone, Qdrant, pgvector, and Weaviate. Methods include concrete parameters, batch handling, and hybrid search patterns that are copy-paste ready. | 3 / 3 |
Workflow Clarity | There is no clear workflow or sequencing for how to implement similarity search end-to-end. The skill presents isolated class templates without guidance on when to use which, no validation/verification steps for search quality, and no error handling or feedback loops for operations like index creation or batch upserts. | 1 / 3 |
Progressive Disclosure | All four complete database implementations are inlined in a single monolithic file with no references to external files. The content would benefit enormously from having the main skill file provide an overview and decision guide, with each database implementation in a separate referenced file. | 1 / 3 |
Total | 6 / 12 Passed |
Validation
90%Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.
Validation — 10 / 11 Passed
Validation for skill structure
| Criteria | Description | Result |
|---|---|---|
skill_md_line_count | SKILL.md is long (554 lines); consider splitting into references/ and linking | Warning |
Total | 10 / 11 Passed | |
- Repository
- wshobson/agents
- Commit
27a7ed9
- 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.