
qdrant-advisor
Diagnose and advise on Qdrant deployments using live skills from skills.qdrant.tech
- GitHub stars
- 271
Add marketplace
/plugin marketplace add qdrant/skillsRun it inside Claude Code once, then install the plugin below.
Install
/plugin install qdrant-advisor@qdrantRun it inside Claude Code after adding the marketplace.
Files
Discovered from sourceQdrant Troubleshooting & Advisory
Core principle
Do not answer Qdrant questions from memory. Qdrant evolves quickly (new endpoints, metrics, defaults, and deployment patterns land often), and the authoritative, current guidance lives at skills.qdrant.tech as a hierarchy of agent skills. Your job is to load the relevant skill context live, then ground your diagnosis in it — loading only the branch that matches the problem, never the whole tree.
You are consuming these skills as context. You are not installing them and nothing needs to be installed.
The knowledge source
- Search:
https://skills.qdrant.tech/search?query=your+query+here - The structure is hierarchical: top-level skill
SKILL.md→ sub-skillSKILL.md→ linked documentation pages. Each level narrows scope. Traverse it depth-first, following only the branch(es) that match the symptom.
Workflow
1. Frame the problem
Pull out the concrete details before fetching anything:
- The symptom(s) in the user's words (e.g. "memory keeps climbing", "queries got slow after a bulk upload", "results are irrelevant").
- The deployment type (local, Docker, self-hosted, Cloud, embedded) and version, if known.
- What changed recently (upgrade, new index, traffic spike, model swap).
Turn these into 1–3 short search phrases.
2. Find the right skill(s)
Use Search (fastest path to the right skill). Fetch https://skills.qdrant.tech/search?query=<your query>, substituting your phrase for your+query+here (encode spaces as + or %20). It returns the single most relevant top-level skill's SKILL.md. Run it more than once for multi-part problems (e.g. one search for the memory symptom, one for the scaling question).
3. Traverse the hierarchy (deep and lateral)
Each SKILL.md you load names its sub-skills (and often related skills and docs) as links. The hierarchy is not just two levels — a skill can nest several layers deep, and skills also reference each other laterally. Follow the links, not a fixed depth.
Descend (go deeper). A SKILL.md is not necessarily a leaf just because you fetched it. If its sections themselves point to further SKILL.md files, keep descending along the branch that matches the symptom — top-level → sub-skill → sub-sub-skill → … — until you reach a level whose guidance is concrete enough to act on (ordered diagnostic steps, exact endpoints/metrics, an explicit "what NOT to do" list). Don't stop early at an intermediate skill that only routes you onward.
Move laterally (go sideways). Real problems often span areas. Follow a link to a sibling or related skill when:
- the current skill explicitly points to another (e.g. a debugging skill that says "if this is actually a capacity problem, see scaling"),
- the symptom has more than one plausible cause living under different top-level skills (e.g. slow queries could be a monitoring/optimizer issue or a performance-optimization issue or a scaling issue), or
- you ran multiple searches in step 2 and they surfaced different skills, each covering part of the problem.
Load each relevant branch, then reconcile what they say in step 4.
Stay disciplined about relevance. Going deep and going sideways is encouraged when the problem warrants it — but still load only branches that bear on the symptom. Don't sweep in unrelated siblings, and stop expanding once you can give a complete, grounded answer. The goal is "all the relevant context and nothing else," not "the whole tree."
Documentation pages. Skills link out to canonical docs (e.g. …/md/documentation/…, qdrant.tech/documentation/…, or qdrant.tech/articles/…). Fetch these links exactly as the SKILL.md provides them — they render as clean markdown natively. Pull a doc page only when you need detail a SKILL.md references but does not itself contain.
4. Diagnose and advise
Synthesize an answer strictly from the loaded context:
- State the most likely cause(s) in priority order — the skills often tell you what to check first (e.g. "check optimizer status before blaming search latency"); preserve that ordering.
- Give concrete, ordered steps: the endpoints to hit, the metrics to read and their thresholds, the config to change.
- Surface the skill's "what NOT to do" warnings explicitly — they prevent common self-inflicted damage.
- Cite the canonical Qdrant doc URLs you relied on so the user can go deeper.
- If the loaded context does not cover the case, say so plainly and either run a different search or fall back to the root index at
https://skills.qdrant.tech— do not paper over the gap with remembered guesses.
Optional: Qdrant MCP tools
If Qdrant MCP tools are connected, use them to supplement the skills. They never replace the skill guidance or its ordered diagnostic steps. If a tool is not available, skip it and continue with the workflow above.
- Qdrant Docs MCP (
search_docs,get_page,search_snippets,list_docs): search the documentation and fetch pages as Markdown, and find code examples by language. This also works where you cannot fetchskills.qdrant.techdirectly. - Qdrant Cloud MCP: when the user runs on Qdrant Cloud, read cluster health, metrics, and logs instead of asking the user to paste them. Read state freely, but ask the user before any change such as restarting, suspending, or deleting a cluster. It manages clusters, backups, and access, not collection data.
Operating notes
- Always fetch fresh every session. Never reuse a previously cached copy of a skill; the registry updates and staleness is exactly what this approach avoids.
- Do not install anything. You are loading context only.
- Fetching: every URL you need is either in this skill (root index
https://skills.qdrant.tech, search base) or surfaced by a page you already fetched (links inside aSKILL.mdor the root index), so each is fetchable as-is. If a constructed search-query URL is ever rejected, fall back to fetching the root index (https://skills.qdrant.tech) and navigate from its absolute links.
Example Workflow
- Symptom: "Our Qdrant node's RAM keeps climbing and it OOM-killed last night. Nothing obvious changed."
- Search: skills.qdrant.tech/search?query=qdrant+memory+growing+OOM
- Follow any sub-skill link on memory or debugging that the returned page names.
- Hop laterally to the scaling skill it references, if capacity is a plausible alternative cause.
- Synthesize from what you loaded; cite the doc URLs. If nothing loaded covers the case, say so; don't fill from memory.
From the qdrant/skills README
Qdrant Skills - Agent Skills for Qdrant Vector Search
Agent skills for building with Qdrant vector search
Skills encode deep Qdrant knowledge so coding agents can make the engineering decisions that determine whether vector search works well: quantization, sharding, tenant isolation, hybrid search, model migration, and more.
Philosophy
Skills are not documentation. Qdrant already has docs in markdown. Skills answer "when?" and "why?", not "how?"
They are structured as the handbook of a Solutions Architect working on Qdrant: given a problem, navigate to the exact place in the documentation where the answer lives. No tutorials, no concept explanations. Only references and minimal snippets where absolutely necessary.
Disclaimer
These skills are under active development. Skill content and structure may change between versions as Qdrant evolves.
Usage
Qdrant maintains a growing set of skills, and their content changes as Qdrant evolves. There are a few ways to give your agent access to them.
Recommended: install the Qdrant Advisor
Install one skill — the Qdrant Advisor — and your agent always has the freshest, most relevant Qdrant guidance, with nothing to manage as the skills change:
npx skills add qdrant/skills/meta/qdrant-advisor
The Advisor ships no static content of its own. When you raise a Qdrant problem, it searches skills.qdrant.tech live, traverses the skill hierarchy along the branch that matches your symptom, and grounds its diagnosis in the current, authoritative guidance, loading only the relevant context. Because it fetches fresh every session, you don't need to reinstall to stay current, and you don't have to remember a URL or hope the site is in the model's training data.
Using the claude.ai web app? The Advisor can't fetch
skills.qdrant.techon its own when you are using the web app. You need to addUse skills.qdrant.techto your prompt (refer to Pass the URL directly).
Alternative: pass the URL directly
If you'd rather not install anything, pass the URL of the skills site in your prompt. The agent fetches the skill relevant to your current problem:
Use skills.qdrant.tech
This keeps context focused, but you have to include the URL in every prompt.
Offline: install the full skill set
If you want the skills available offline, or triggered automatically without the Advisor, install the complete set locally. See the Installation section.
Quick Start
With the Qdrant Advisor installed, just ask your agent about Qdrant. The Advisor triggers automatically and loads the matching guidance live:
"I have 50M vectors on a single node and search is slow, should I add more nodes?"
→ Advisor loads the scaling guidance, recommends quantization and vertical scaling before adding nodes
"My search results are returning irrelevant matches"
→ Advisor loads the search-quality guidance, walks through diagnosis and search strategy options
"How do I switch from OpenAI embeddings to Cohere without downtime?"
→ Advisor loads the model-migration guidance for a zero-downtime switch with dual vectors
Prefer the URL method? Add Use skills.qdrant.tech to the same prompts:
"I have 50M vectors on a single node and search is slow, should I add more nodes? Use skills.qdrant.tech"
"My search results are returning irrelevant matches. Use skills.qdrant.tech"
Skills
| Skill | Useful for |
|---|---|
| qdrant-clients-sdk | SDK setup, code examples, snippet search across Python, TypeScript, Rust, Go, .NET, Java |
| qdrant-scaling | Scaling decisions: data volume, QPS, latency, query volume, horizontal vs vertical |
| qdrant-sizing | Sizing RAM, disk, CPU, and node count before a deployment is provisioned. |
| qdrant-performance-optimization | Search speed, memory usage, indexing performance |
| qdrant-search-quality | Diagnosing bad results, search strategies, hybrid search |
| qdrant-monitoring | Metrics, health checks, debugging optimizer and cluster issues |
| qdrant-multitenancy | Isolating multiple tenants within a Qdrant deployment: payload partitioning, tiered multitenancy, and region-based data isolation |
| qdrant-deployment-options | Choosing between local, self-hosted, cloud, and hybrid |
| qdrant-managed-cloud-quickstart | Getting a first Managed Cloud cluster running and connected: free vs standard, API keys, strict mode, Cloud Inference, and choices you can't undo |
| qdrant-hybrid-cloud-setup | Setting up Hybrid Cloud on your own Kubernetes: prerequisites, storage/CSI, agent/operator install, exposure, and pitfalls |
| qdrant-edge | Building on the embedded shard: server sync, on-device BM25, snapshots, reuse vs reimplement |
| qdrant-migration-tool | Using the Qdrant Migration Tool CLI to move data from another vector database into Qdrant |
| qdrant-model-migration | Switching embedding models without downtime |
| qdrant-version-upgrade | Safe upgrade paths, compatibility guarantees, rolling upgrades |
Installation
Qdrant Advisor (recommended)
If you want a single, always-current skill instead of the full set, install only the Qdrant Advisor:
npx skills add qdrant/skills/meta/qdrant-advisor
This installs just the qdrant-advisor meta-skill. It ships no static content of its own, it loads the relevant Qdrant skills live from skills.qdrant.tech on demand, so you always get the latest guidance without reinstalling. It is a separate install, not part of the npx skills add qdrant/skills bundle. In Claude Code, install it as the qdrant-advisor plugin instead (see Claude Code).
npx skills
Install using the npx skills CLI:
npx skills add qdrant/skills
Claude Code
Add the marketplace, then install all Qdrant skills:
/plugin marketplace add qdrant/skills
/plugin install qdrant@qdrant
To install only the Qdrant Advisor, which loads the latest skills live from skills.qdrant.tech instead of bundling them:
/plugin install qdrant-advisor@qdrant
The plugin also bundles two hosted MCP servers: Qdrant Docs (no sign-in) and Qdrant Cloud (OAuth, run /mcp and select qdrant-cloud to sign in).
Cursor
Install from the Cursor Marketplace or add manually via Settings > Rules > Add Rule > Remote Rule (GitHub) with qdrant/skills.
Clone / Copy
Clone this repo and copy the skill folders into the appropriate directory for your agent:
| Agent | Skill Directory | Docs |
|---|---|---|
| Claude Code | ~/.claude/skills/ | docs |
| Cursor | .cursor/skills/ | docs |
| OpenCode | ~/.config/opencode/skill/ | docs |
| OpenAI Codex | ~/.codex/skills/ | docs |
| Pi | ~/.pi/agent/skills/ | docs |
MCP Servers
For additional Qdrant context, pair skills with these MCP servers:
| Server | Purpose |
|---|---|
| mcp-code-snippets | Search Qdrant docs and code examples across all SDKs |
| mcp-server-qdrant | Store and retrieve memories, manage collections directly |
Getting Help
Found a bug or wrong advice in a skill? Open an issue on GitHub and include:
- The skill name
- The prompt you gave your agent
- What the agent said vs what it should have said
Contributing
If you are interested in contributing, follow the instructions in CONTRIBUTING.md.
Details
- Marketplace
- qdrant/skills
- Source
- plugins/qdrant-advisor
- Category
- Community
More from qdrant/skills
All 2Similar to qdrant-advisor
More Development Tools
reamorluto/rea466.8K starsReverse engineer anything with agents, from app behavior down to native binaries.
superpowersobra/superpowers319.5K starsCore skills library for Claude Code: TDD, debugging, collaboration patterns, and proven techniques
claude-apianthropics/skills196.9K starsClaude API and SDK documentation skill for building LLM-powered applications
prompts.chatf/prompts.chat178.2K starsAccess thousands of AI prompts and skills directly in your AI coding assistant. Search prompts, discover skills, save your own, and improve prompts with AI.
agent-sdk-devanthropics/claude-code156.1K starsDevelopment kit for working with the Claude Agent SDK
ui-ux-pro-maxnextlevelbuilder/ui-ux-pro-max-skill152.6K starsProfessional UI/UX design intelligence for AI coding assistants. Includes searchable databases of styles, colors, typography, charts, and UX guidelines for Reac