How to use the Similarity Search Patterns agent skill

What does the similarity-search-patterns skill make the agent do?

Once installed, the skill lets the agent discuss and plan vector-based similarity search. It covers when to use this kind of search: semantic search systems, RAG retrieval, recommendation engines, reducing search latency, scaling to millions of vectors, and combining semantic and keyword search.

The skill's guidance includes distance metrics (cosine, Euclidean/L2, dot product and Manhattan/L1), a comparison of index types (Flat, HNSW and IVF+PQ), and a list of do's and don'ts for production search. For concrete code, it points the agent to a reference file with templates and worked examples, which the agent reads when needed.

• Explain which distance metric suits normalized embeddings versus raw embeddings
• Compare Flat (exact), HNSW (graph-based) and IVF+PQ (quantized) indexes for your data size
• Suggest tuning parameters such as ef_search and nprobe for the recall versus speed trade-off
• Recommend hybrid search, measuring recall, pre-filtering and watching storage costs

How do you install the similarity-search-patterns skill?

Download the ZIP file for the skill from the page you are reading. Unzip it so that the skill folder sits in one of these locations: your personal skills folder at ~/.claude/skills/, or a project's .claude/skills/ folder if you want the skill available only inside that project.

If you use the Claude apps instead, you can upload the skill under Settings → Capabilities → Skills rather than placing files on disk.

The skill folder contains two files: SKILL.md, which holds the main instructions, and references/details.md, which holds the templates and worked examples.

• Personal install: ~/.claude/skills/
• Project install: .claude/skills/ inside your project
• Claude apps: Settings → Capabilities → Skills, then upload

How do you trigger the skill with a natural request?

You do not need a special command. The skill's description says it applies when you are building semantic search, implementing nearest neighbor queries, or optimizing retrieval performance, so ask for that work in ordinary language and mention your situation.

The more concrete your request (data size, latency target, embedding model, existing database), the more useful the agent's answer will be.

• 'I am building semantic search over 2 million support articles. Should I use HNSW or IVF+PQ?'
• 'Explain the difference between cosine and Euclidean distance for my embeddings.'
• 'My vector search is fast but misses relevant results. How do I tune recall?'
• 'Review my retrieval plan for a RAG app and suggest a hybrid keyword and vector setup.'

What do the index and metric choices look like in practice?

The skill's comparison table is a starting point. Flat indexes give exact results (100% recall) and suit small data. HNSW is the default recommendation in the skill for most cases. IVF+PQ suits very large collections. The skill lists approximate complexity and recall figures for each, but these are general approximations, so measure recall on your own data before relying on them.

Cosine distance suits normalized embeddings, Euclidean (L2) suits raw embeddings, and dot product suits cases where magnitude matters.

• Start with a flat index and scale up only when latency or size requires it
• Measure search quality (recall) on a test set from your own data
• Use pre-filtering to reduce the search space when your metadata allows it
• Factor in vector storage costs as the collection grows

What does the skill need, and what are the safety notes?

The skill lists no required tools or packages. It does not run scripts and does not use the network, so the skill files themselves are plain instructions and reference text.

The reference file includes a Pinecone example that takes an API key and creates a serverless index on a cloud provider. If you adapt that template, you would be using your own account with that vendor, and you should review the code and keep keys out of shared files.

• Requires: nothing listed
• Runs scripts: no
• Uses network: no
• Templates in references/details.md are examples you must adapt and test yourself

What tips help you get the most from it?

Treat the skill as a checklist and a design aid, not a finished search product. Ask the agent to justify its recommendation against your data size and latency needs, and then verify the claim with a test.

Watch tail latency as well as average latency, because the skill notes that P99 matters for user experience.

• Test with your own queries and labelled relevant results before scaling
• Compare two index types on the same data set
• Keep a record of recall and latency for each parameter change