New advertisers: 50% off your first month with code FIRSTMONTHSee slots
qdrant avatar

qdrant-advisor

Diagnose and advise on Qdrant deployments using live skills from skills.qdrant.tech

GitHub stars
271
View on GitHub

Add marketplace

/plugin marketplace add qdrant/skills

Run it inside Claude Code once, then install the plugin below.

Install

/plugin install qdrant-advisor@qdrant

Run it inside Claude Code after adding the marketplace.

Files

Discovered from source

Qdrant 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-skill SKILL.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 fetch skills.qdrant.tech directly.
  • 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 a SKILL.md or 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

  1. Symptom: "Our Qdrant node's RAM keeps climbing and it OOM-killed last night. Nothing obvious changed."
  2. Search: skills.qdrant.tech/search?query=qdrant+memory+growing+OOM
  3. Follow any sub-skill link on memory or debugging that the returned page names.
  4. Hop laterally to the scaling skill it references, if capacity is a plausible alternative cause.
  5. 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

Qdrant

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.tech on its own when you are using the web app. You need to add Use skills.qdrant.tech to 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

SkillUseful for
qdrant-clients-sdkSDK setup, code examples, snippet search across Python, TypeScript, Rust, Go, .NET, Java
qdrant-scalingScaling decisions: data volume, QPS, latency, query volume, horizontal vs vertical
qdrant-sizingSizing RAM, disk, CPU, and node count before a deployment is provisioned.
qdrant-performance-optimizationSearch speed, memory usage, indexing performance
qdrant-search-qualityDiagnosing bad results, search strategies, hybrid search
qdrant-monitoringMetrics, health checks, debugging optimizer and cluster issues
qdrant-multitenancyIsolating multiple tenants within a Qdrant deployment: payload partitioning, tiered multitenancy, and region-based data isolation
qdrant-deployment-optionsChoosing between local, self-hosted, cloud, and hybrid
qdrant-managed-cloud-quickstartGetting 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-setupSetting up Hybrid Cloud on your own Kubernetes: prerequisites, storage/CSI, agent/operator install, exposure, and pitfalls
qdrant-edgeBuilding on the embedded shard: server sync, on-device BM25, snapshots, reuse vs reimplement
qdrant-migration-toolUsing the Qdrant Migration Tool CLI to move data from another vector database into Qdrant
qdrant-model-migrationSwitching embedding models without downtime
qdrant-version-upgradeSafe 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:

AgentSkill DirectoryDocs
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:

ServerPurpose
mcp-code-snippetsSearch Qdrant docs and code examples across all SDKs
mcp-server-qdrantStore 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 2

Similar to qdrant-advisor

More Development Tools