similarity-search-patterns
- Use it when:
- You're building semantic search, RAG retrieval or a recommendation engine over embeddings.
- It does:
- Helps pick a distance metric and an index type for your data size and recall/latency needs.
- You get:
- A design; a reference file holds the templates and worked examples.
- Choices:
- Cosine, Euclidean, dot-product or Manhattan distance; a flat (exact), HNSW (graph) or IVF+PQ (quantized) index, with their speed and recall trade-offs.
TL;DR
A short reference for production similarity search. The SKILL.md tabulates four distance metrics and when each fits — cosine for normalized embeddings, Euclidean for raw vectors, dot product when magnitude matters, Manhattan for sparse vectors — and three index families with their complexity and recall: flat exact search (O(n), 100% recall, small data), HNSW (O(log n), 95–99%, medium to large) and IVF+PQ (O(√n), 90–95%, very large). Its advice: use HNSW for most cases, tune ef_search or nprobe for the recall/speed balance, add keyword search for hybrid retrieval, pre-filter to shrink the search space, measure recall before optimizing, start flat and scale up, watch P99 latency, and remember storage cost. The templates and worked examples are in a reference file.
Summarizes the skill at 4bde316.
npx skills add https://github.com/wshobson/agents --skill similarity-search-patterns skills.sh pageSource on GitHubAll skills from wshobson/agents
Fewer weekly downloads than 72% of skills
Weekly values
| Week to | Installs |
|---|---|
| Sep 21 | 184 |
| Sep 28 | 216 |
| Oct 5 | 264 |
| Oct 12 | 208 |
| Oct 19 | 182 |
| Oct 26 | 179 |
| Nov 2 | 167 |
| Nov 9 | 149 |
More downloads than 55% of skills
More stars than 76% of repos
Older than 82% of skills
| Category |
Build agents, orchestrate workers and give agents memory. Everything for building software: planning, coding, debugging, design, frameworks, cloud, agents and skills. |
|---|---|
| Type |
Knowledge and rules the agent applies while it works: best practices, design principles, API references. |
| Effect |
Adds no side effects of its own. It shapes how the agent thinks, writes or reviews. Guidelines and routers are always effect:none, even when the task they support edits code. |
| Needs |
Instructions only. Works in any agent that supports skills. |
| Publisher |
Everyone else. Unverified vendor claims default to community. |
| Topics |
SKILL.md
From wshobson/agents at 4bde316. Checked daily, last changed Nov 6, 2026.
Frontmatter
name: similarity-search-patterns
description: Implement efficient similarity search with vector databases. Use when building semantic search, implementing nearest neighbor queries, or optimizing retrieval performance.Similarity Search Patterns
Patterns for implementing efficient similarity search in production systems.
When to Use This Skill
- Building semantic search systems
- Implementing RAG retrieval
- Creating recommendation engines
- Optimizing search latency
- Scaling to millions of vectors
- Combining semantic and keyword search
Core Concepts
1. Distance Metrics
| Metric | Formula | Best For | | ------------------ | ------------------ | --------------------- | --- | -------------- | | Cosine | 1 - (A·B)/(‖A‖‖B‖) | Normalized embeddings | | Euclidean (L2) | √Σ(a-b)² | Raw embeddings | | Dot Product | A·B | Magnitude matters | | Manhattan (L1) | Σ | a-b | | Sparse vectors |
2. Index Types
┌─────────────────────────────────────────────────┐
│ Index Types │
├─────────────┬───────────────┬───────────────────┤
│ Flat │ HNSW │ IVF+PQ │
│ (Exact) │ (Graph-based) │ (Quantized) │
├─────────────┼───────────────┼───────────────────┤
│ O(n) search │ O(log n) │ O(√n) │
│ 100% recall │ ~95-99% │ ~90-95% │
│ Small data │ Medium-Large │ Very Large │
└─────────────┴───────────────┴───────────────────┘
Templates and detailed worked examples
Full template library and detailed worked examples live in references/details.md. Read that file when you need the concrete templates.
Best Practices
Do's
- Use appropriate index - HNSW for most cases
- Tune parameters - ef_search, nprobe for recall/speed
- Implement hybrid search - Combine with keyword search
- Monitor recall - Measure search quality
- Pre-filter when possible - Reduce search space
Don'ts
- Don't skip evaluation - Measure before optimizing
- Don't over-index - Start with flat, scale up
- Don't ignore latency - P99 matters for UX
- Don't forget costs - Vector storage adds up