Skip to content
Get packs

Guide · Agent skill

How to use the FAISS Vector Search agent skill

Updated · written with AI from the project's own documentation and checked against our catalogue data

The FAISS skill teaches an AI agent how to use Facebook's FAISS library, which finds the most similar items in large collections of numeric vectors such as text or image embeddings. This guide explains what the skill does, how to install it, how to trigger it with plain requests, and what you need before running the code it produces. After reading it you will be able to get the skill running and know when FAISS is the right tool.

FAISS Vector SearchOrchestra-Research/AI-Research-SKILLs · MIT

Quick start

  1. 1Download and unzip the skill. Download the ZIP from this skill's page and unzip it into ~/.claude/skills/ or your project's .claude/skills/ folder.
  2. 2Install Python dependencies. Run pip install faiss-cpu, or pip install faiss-gpu if you have a CUDA-capable NVIDIA GPU. Make sure numpy is installed.
  3. 3Describe your search task. Tell the agent what you are searching, how many vectors you have, and whether you need exact results.
  4. 4Review the index choice. Check the index type the agent picks against the dataset-size guidance in the skill.
  5. 5Run the generated code. Run the script on a sample of your data first to confirm dimensions and results look right.
  6. 6Save the index. Use faiss.write_index so you do not have to rebuild a trained index every time.

What the FAISS skill makes the agent do

Agent skills are folders of instructions that an AI agent loads when a task matches them. The FAISS skill covers similarity search over dense vectors, the numeric representations that embedding models produce from text, images or other content.

With the skill loaded, the agent can write Python code that builds different kinds of search indexes: exact (Flat), approximate inverted-file (IVF), graph-based (HNSW) and memory-saving product quantization (PQ). It can also save and reload indexes, move them onto GPUs, and connect them to LangChain or LlamaIndex.

  • Exact search with IndexFlatL2 or IndexFlatIP
  • Approximate search with IndexIVFFlat, IndexHNSWFlat or IndexPQ
  • Saving and loading indexes with write_index and read_index
  • GPU use through single-GPU or all-GPU helpers
  • LangChain and LlamaIndex vector store integration

Install the FAISS skill

Download the ZIP file from the skill's page on this site and unzip it. You can then place the folder in one of two locations: ~/.claude/skills/ to make the skill available to you across projects, or a project's .claude/skills/ folder to share it only with that project.

If you use the Claude apps instead, upload the skill under Settings → Capabilities → Skills.

  • Personal install: unzip into ~/.claude/skills/
  • Project install: unzip into the project's .claude/skills/ folder
  • Claude apps: upload under Settings → Capabilities → Skills

Install the FAISS Python package

The skill's examples need the faiss package. The source lists two options: a CPU-only build and a GPU build. Choose the GPU build only if you have a CUDA-capable NVIDIA GPU.

  • faiss-cpu for machines without a GPU
  • faiss-gpu for machines with a CUDA-capable NVIDIA GPU
  • numpy is also required
# CPU only pip install faiss-cpu # GPU support pip install faiss-gpu

Trigger the skill with natural requests

You do not need special syntax. Describe the search problem in plain language and mention vectors, embeddings, nearest neighbours or similarity search. The agent matches the request to the skill's description and uses its patterns.

Be specific about your data size, whether you need exact results, and whether you have a GPU. Those details decide which index type the agent should choose.

  • "Build a FAISS index over 500,000 product embeddings and return the 10 nearest neighbours for a query vector."
  • "Use FAISS to save my document embeddings to disk and reload them later."
  • "Set up a LangChain vector store with FAISS for my docs."

Choose an index type

The skill's index guide suggests a rough rule by dataset size. Flat indexes give exact results but are slow on large data. IVF is fast and approximate and needs training. HNSW gives high accuracy and speed without training but uses more memory. IVF+PQ suits very large datasets where memory is tight.

Treat these figures as the skill's guidance, not guarantees. Actual speed and accuracy depend on your data and settings.

  • Under 10K vectors: Flat (exact)
  • 10K to 1M vectors: IVF (needs training)
  • 1M to 10M vectors: HNSW
  • Over 10M vectors: IVF+PQ (low memory)

Save, reload and use GPUs

Trained indexes are expensive to build, so the skill recommends saving them. Write an index to a file and read it back when you need it. For GPU use, the skill creates GPU resources and moves a CPU index onto GPU 0, or onto all available GPUs.

  • Save with faiss.write_index and load with faiss.read_index
  • Single GPU: faiss.index_cpu_to_gpu
  • All GPUs: faiss.index_cpu_to_all_gpus
# Save index faiss.write_index(index, "large.index") # Load index index = faiss.read_index("large.index")

What people use it for

  • Finding similar products or documents from embedding vectors for a recommendation or search feature
  • Running batch similarity search or clustering on large vector datasets
  • Adding FAISS as the vector store behind a LangChain or LlamaIndex retrieval pipeline
  • Speeding up k-nearest-neighbour lookups with a GPU

Frequently asked questions

How do I install the FAISS skill?

Download the ZIP from this skill's page and unzip it into ~/.claude/skills/ or a project's .claude/skills/ folder. In the Claude apps, you can upload it under Settings → Capabilities → Skills.

What do I need to use the FAISS skill?

You need Python, the faiss-cpu or faiss-gpu package, and numpy. The GPU build needs a CUDA-capable NVIDIA GPU. LangChain examples also need langchain-community and langchain-openai, and an OpenAI API key.

Is FAISS free to use?

The skill is listed under the MIT licence, and the FAISS library is the open-source project from Facebook AI Research linked on the skill page. Check the licence file in the repository for the exact terms that apply to you.

Does FAISS store metadata or filter results by fields?

No. The skill describes FAISS as pure vector similarity search without metadata filtering. For metadata filtering or full database features, the skill points to alternatives such as Chroma, Pinecone or Weaviate.

Should I use FAISS or Chroma?

Use FAISS for high-performance pure similarity search over large embedding sets, especially with GPUs. The skill suggests Chroma or Pinecone when you need metadata filtering, and Weaviate when you need full database features.

Why does loading a LangChain FAISS store need a special flag?

The LangChain example passes allow_dangerous_deserialization=True when loading a saved store. Only load index files you created or trust, because loading them can run untrusted code.

New agent skills, repos and AI tools — every week

The best new skills and open-source projects, the fastest-growing repos, and one free prompt. Five minutes to read. Unsubscribe anytime.

Our verdict

This skill suits Python developers and data teams building similarity search over many embeddings, especially where GPUs are available. If you need metadata filtering, a full database with updates and access control, or a finished app rather than code patterns, pick a different tool. For a small dataset, an exact search may be enough without the extra setup.

Download the skill