Guide · Agent skill
How to use the Qdrant Vector Search agent skill
Updated · written with AI from the project's own documentation and checked against our catalogue data
The Qdrant Vector Search skill is a set of instructions that teaches an AI agent how to use Qdrant, an open-source vector database, to store text as numerical embeddings and find similar items quickly. This guide is for readers who have not used agent skills before and want a working Qdrant setup in Python. By the end you will know how to install the skill, ask for Qdrant help in plain language, and understand what the agent will write for you and what it needs to run.
Qdrant Vector SearchOrchestra-Research/AI-Research-SKILLs · MIT Download the skill Quick start
- 1Download and unzip the skill. Download the ZIP from this page and unzip it. Keep the qdrant-vector-search folder intact.
- 2Place it in the skills folder. Move the folder into ~/.claude/skills/ for all projects, or into a project's .claude/skills/ folder for one project. Alternatively, upload it under Settings → Capabilities → Skills in the Claude apps.
- 3Install the Python client. Run pip install qdrant-client, using version 1.12.0 or newer.
- 4Start a Qdrant server. Run the qdrant/qdrant Docker image with ports 6333 and 6334 published, adding a volume if you want data to persist.
- 5Ask for what you need. Describe your task in plain language, such as creating a collection with metadata filtering for your documents.
- 6Run and check the code. Run the code the agent writes against your local server and confirm the search results look right before scaling up.
What the skill makes the agent do
Once installed, the agent knows how to create Qdrant collections, insert points (an ID, a vector and a payload of metadata), and run nearest-neighbour searches. It can also add filters on payload fields such as category or timestamp, so results match both meaning and metadata.
These are the building blocks of retrieval-augmented generation (RAG) and semantic search. The skill's source also explains when Qdrant fits better than alternatives such as Chroma, FAISS, Pinecone or Weaviate.
- Create a collection with a vector size and distance metric (COSINE, EUCLID, DOT or MANHATTAN)
- Insert or upsert points with payload metadata
- Run filtered search with must and must_not conditions
- Set up a basic RAG retrieval function with sentence-transformers
Install the skill
Download the skill ZIP from this page and unzip it. For Claude Code, place the unzipped folder in ~/.claude/skills/ to make it available everywhere, or in a project's .claude/skills/ folder to limit it to that project.
In the Claude apps, you can instead upload the skill under Settings → Capabilities → Skills.
- Personal (all projects): ~/.claude/skills/
- Single project: .claude/skills/ inside the project folder
- Claude apps: Settings → Capabilities → Skills, then upload
Set up Qdrant and the Python client
The skill expects Python with the qdrant-client library, version 1.12.0 or newer, and a running Qdrant server. The skill recommends Docker for local development. Optionally, install sentence-transformers if you want the agent to generate embeddings.
- Python client: install qdrant-client
- Server: run the qdrant/qdrant Docker image on ports 6333 and 6334
- Persistent data: mount a local folder to /qdrant/storage
- Optional: sentence-transformers for embeddings
pip install qdrant-client
docker run -p 6333:6333 -p 6334:6334 qdrant/qdrant
docker run -p 6333:6333 -p 6334:6334 \
-v $(pwd)/qdrant_storage:/qdrant/storage \
qdrant/qdrantTrigger the skill with natural requests
You do not need to name the skill. Describe the task in plain words that match the skill's purpose, such as building a RAG system, adding semantic search, or storing embeddings with metadata filters. Mention Qdrant if you want it used specifically.
Be specific about your data and constraints, such as the vector size of your embedding model, which metadata fields you need to filter on, and whether the server runs locally or in production.
- "Set up a Qdrant collection for my support articles, filtered by product and language."
- "Write a retrieve function using Qdrant that returns the top 5 chunks with their source."
- "Compare Qdrant with Chroma for my RAG prototype and tell me which to use."
Check the troubleshooting notes
The skill includes a troubleshooting reference covering common errors. Docker daemon problems and port conflicts are covered, as are missing qdrant_client modules, gRPC errors and connection refusals. If you hit one of these, ask the agent to check the troubleshooting guidance for your error message.
- ModuleNotFoundError: install qdrant-client, optionally pinned to 1.12.0 or newer
- Port 6333 already in use: map a different host port to the container
- grpc errors: install qdrant-client with gRPC support or set prefer_grpc to false
- Connection refused: confirm the Qdrant server is running
Safety notes: network use and scripts
This skill does not run scripts. It does use the network, because the code it writes connects to a Qdrant server, usually at localhost on port 6333. The skill's requirements do not mention API keys. Review any code the agent produces before running it, especially if you point it at a remote host.
- Runs scripts: no
- Uses network: yes, to reach your Qdrant server
- Review generated code before running it against shared or production data
What people use it for
- Semantic search over a knowledge base of help articles or internal documents
- A RAG pipeline that retrieves the most relevant chunks before sending them to a language model
- Search filtered by metadata, such as only tech articles or only items with a price range
- Comparing vector databases before choosing one for a production project
Frequently asked questions
Is the Qdrant Vector Search skill free?
The skill is published under the MIT licence, as listed on this page. Qdrant itself is an open-source vector database, but check its own licence and hosting costs if you run it in production.
What do I need to use this skill?
You need Python with the qdrant-client library version 1.12.0 or newer, and a running Qdrant server, typically started with the qdrant/qdrant Docker image. sentence-transformers is optional, for generating embeddings.
How do I install the Qdrant skill in Claude?
Download the ZIP from this 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.
Does this skill run scripts on my computer?
No, the skill does not run scripts. It does use the network, because the code connects to a Qdrant server, usually on localhost port 6333.
Qdrant or Chroma: which should I choose?
The skill suggests Chroma for simpler setups and embedded use cases. Qdrant suits production RAG that needs metadata filtering, scaling with sharding and replication, or on-premise deployment with full data control.
Why does my Python client fail with a connection refused error?
Usually the Qdrant server is not running or the port is wrong. Start the Docker container with ports 6333 and 6334 published, then check that the client points to localhost on port 6333.
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 developers building a production RAG or semantic search feature who need metadata filtering and a self-hosted vector store. If you only need a quick embedded prototype, Chroma is simpler, and if you want zero infrastructure work, a fully managed service such as Pinecone may fit better.
Download the skill