How qdrant/skills works
1. Repository purpose
- This repo is a curated content pack of “agent skills” for Qdrant Vector Search, not an application runtime. Its job is to give coding agents decision-making guidance for specific Qdrant scenarios such as scaling, search quality, migration, monitoring, and deployment choices.
2. Primary content layer
- The core architecture is the skills/ tree.
- Each skill lives in its own folder with a SKILL.md entrypoint, and some skills are decomposed into nested subskills for narrower decisions.
- skills/index.md acts as the catalog/navigation hub for the whole set.
3. Skill domain boundaries
- Skills are organized by operational concern, not by product feature area: qdrant-scaling, qdrant-search-quality, qdrant-performance-optimization, qdrant-monitoring, qdrant-model-migration, qdrant-version-upgrade, qdrant-deployment-options, and qdrant-clients-sdk.
- This suggests a handbook-style architecture where each skill answers “when/why” for a bounded problem domain, rather than providing a single unified tutorial system.
4. Nested specialization
- Several top-level skills split into deeper subdomains, for example:
- scaling data volume vs QPS vs query volume
- performance optimization by indexing, memory, or search speed
- search quality via diagnosis, strategies, hybrid search, and relevance feedback
- This hierarchy is important for diagramming because it shows a top-level domain layer with focused leaf nodes underneath.
5. Distribution and consumption path
- The skills are intended to be consumed by external agents through hosted URLs at skills.qdrant.tech, or installed locally into agent-specific skill directories.
- The repo therefore serves both as source content and as the deployment artifact for agent-facing knowledge.
6. Agent/platform integration
- README.md and .claude-plugin/ show first-class support for Claude Code marketplace installation.
- The repo also documents Cursor and other agent ecosystems, so the same content is packaged for multiple agent runtimes, not just one.
7. Publishing and site generation
- netlify.toml indicates the skills site is likely published as a static site.
- build.sh, scripts/generate_sitemap.sh, and scripts/make_links_absolute.py suggest a build pipeline that prepares markdown content for web hosting and ensures links work correctly in the published site.
8. Content validation and transformation
- scripts/validate_skills.py and the GitHub workflow validate-skills.yml imply a validation gate for skill structure and metadata.
- scripts/test_make_links_absolute.py shows there is at least one automated transformation concern: rewriting relative links into site-safe absolute links.
9. Evaluation loop
- The evals/ directory and scripts/run_eval.py plus eval-skills.yml indicate the repo includes an evaluation harness for checking whether skills produce the intended guidance.
- This is a key architecture boundary: authored markdown is not enough; skills are also measured against scenarios.
10. Link integrity and maintenance
- .github/workflows/links.yml, .lycheeignore, and the link-rewrite script indicate link correctness is treated as a separate concern from content authoring.
- stale.yml, dependabot.yml, templates, and CODEOWNERS show standard governance and maintenance automation around the content pipeline.
11. Operational model of the repository
- The repo is effectively a content monorepo with three layers: authoring (skills/), automation (scripts/, evals/), and distribution (Netlify, Claude plugin metadata, marketplace config).
- There is no backend service or application state; the main “runtime” is external agents fetching and using markdown skills.
12. External references and dependencies
- The skills intentionally point outward to Qdrant docs, SDK examples, and related tooling rather than duplicating full documentation.
- That makes the repo a routing layer for expert guidance, with the canonical source of detailed technical content remaining outside this repository.
Main entry points: index.md Skills index · qdrant-scaling/SKILL.md Scaling · scaling-data-volume/SKILL.md Data volume · qdrant-performance-optimization/SKILL.md Performance
Components 34
Authoring
Curated skill content organized by Qdrant operational concern.
- Skills index · Top-level navigation hub for the skill set.
skills/index.md - Scaling · Guidance for data volume, QPS, query volume, and latency scaling.
skills/qdrant-scaling/SKILL.md - Data volume · Scaling strategies for growing collections and tenants.
skills/qdrant-scaling/scaling-data-volume/SKILL.md - Horizontal · Distribute data across nodes or shards.
skills/qdrant-scaling/scaling-data-volume/horizontal-scaling/SKILL.md - Vertical · Increase per-node capacity for larger datasets.
skills/qdrant-scaling/scaling-data-volume/vertical-scaling/SKILL.md - Tenant scale · Partition or isolate growth by tenant.
skills/qdrant-scaling/scaling-data-volume/tenant-scaling/SKILL.md - Time window · Use sliding windows to bound retained data.
skills/qdrant-scaling/scaling-data-volume/sliding-time-window/SKILL.md - QPS · Increase throughput for concurrent request load.
skills/qdrant-scaling/scaling-qps/SKILL.md - Query volume · Handle large numbers of queries over time.
skills/qdrant-scaling/scaling-query-volume/SKILL.md - Latency · Reduce end-to-end request latency under load.
skills/qdrant-scaling/minimize-latency/SKILL.md - Search quality · Improve relevance, retrieval strategy, and diagnosis.
skills/qdrant-search-quality/SKILL.md - Diagnosis · Troubleshoot poor search results and relevance issues.
skills/qdrant-search-quality/diagnosis/SKILL.md - Strategies · Choose retrieval patterns and ranking approaches.
skills/qdrant-search-quality/search-strategies/SKILL.md - Hybrid search · Combine sparse and dense retrieval approaches.
skills/qdrant-search-quality/search-strategies/hybrid-search/SKILL.md - Combine searches · Merge and reconcile multiple retrieval signals.
skills/qdrant-search-quality/search-strategies/hybrid-search/combining-searches/SKILL.md - Search types · Select the appropriate retrieval mode for a scenario.
skills/qdrant-search-quality/search-strategies/hybrid-search/search-types/SKILL.md - Relevance feedback · Use feedback loops to refine search quality.
skills/qdrant-search-quality/search-strategies/relevance-feedback/SKILL.md - Performance · Optimize indexing, memory usage, and search speed.
skills/qdrant-performance-optimization/SKILL.md - Indexing · Tune indexing behavior and tradeoffs.
skills/qdrant-performance-optimization/indexing-performance-optimization/SKILL.md - Memory · Reduce memory footprint and improve efficiency.
skills/qdrant-performance-optimization/memory-usage-optimization/SKILL.md - Search speed · Improve query execution speed.
skills/qdrant-performance-optimization/search-speed-optimization/SKILL.md - Monitoring · Set up observability and debug operational issues.
skills/qdrant-monitoring/SKILL.md - Setup · Instrument and configure monitoring signals.
skills/qdrant-monitoring/setup/SKILL.md - Debugging · Investigate incidents and runtime symptoms.
skills/qdrant-monitoring/debugging/SKILL.md - Model migration · Move embeddings or models across versions or providers.
skills/qdrant-model-migration/SKILL.md - Version upgrade · Guide Qdrant version upgrade decisions and process.
skills/qdrant-version-upgrade/SKILL.md - Deployment · Choose deployment topology or hosting option.
skills/qdrant-deployment-options/SKILL.md - Clients SDK · Use Qdrant client libraries and SDKs effectively.
skills/qdrant-clients-sdk/SKILL.md
Automation
Build, validation, evaluation, and link maintenance workflows.
- Build · Prepare markdown content for publishing.
build.sh - Validate skills · Check skill structure and metadata before publishing.
scripts/validate_skills.py - Rewrite links · Convert relative links into site-safe absolute links.
scripts/make_links_absolute.py - Sitemap · Generate site navigation metadata for hosted publishing.
scripts/generate_sitemap.sh - Run evals · Execute scenario-based evaluation of skills guidance.
scripts/run_eval.py - Evals config · Scenario definitions for skill evaluation.
evals/evals.json
Connections 34
- Skills index → Scaling: catalogs · Index points to major skill domains.
- Skills index → Search quality: catalogs · Index points to major skill domains.
- Skills index → Performance: catalogs · Index points to major skill domains.
- Skills index → Monitoring: catalogs · Index points to major skill domains.
- Skills index → Model migration: catalogs · Index points to major skill domains.
- Skills index → Version upgrade: catalogs · Index points to major skill domains.
- Skills index → Deployment: catalogs · Index points to major skill domains.
- Skills index → Clients SDK: catalogs · Index points to major skill domains.
- Scaling → Data volume: specializes · Top-level scaling splits into data-volume concerns.
- Scaling → QPS: specializes · Top-level scaling splits into QPS concerns.
- Scaling → Query volume: specializes · Top-level scaling splits into query-volume concerns.
- Scaling → Latency: specializes · Top-level scaling includes latency minimization.
- Data volume → Horizontal: includes · Data-volume scaling includes horizontal scaling.
- Data volume → Vertical: includes · Data-volume scaling includes vertical scaling.
- Data volume → Tenant scale: includes · Data-volume scaling includes tenant-aware scaling.
- Data volume → Time window: includes · Data-volume scaling includes bounded retention patterns.
- Search quality → Diagnosis: specializes · Search quality splits into diagnosis and strategy.
- Search quality → Strategies: specializes · Search quality splits into diagnosis and strategy.
- Strategies → Hybrid search: includes · Strategy guidance includes hybrid retrieval.
- Hybrid search → Combine searches: includes · Hybrid search covers combining multiple searches.
- Hybrid search → Search types: includes · Hybrid search covers choosing search types.
- Strategies → Relevance feedback: includes · Strategy guidance includes feedback loops.
- Performance → Indexing: specializes · Performance optimization splits by concern.
- Performance → Memory: specializes · Performance optimization splits by concern.
- Performance → Search speed: specializes · Performance optimization splits by concern.
- Monitoring → Setup: specializes · Monitoring splits into setup and debugging.
- Monitoring → Debugging: specializes · Monitoring splits into setup and debugging.
- Build → Rewrite links: uses · Build flow depends on link rewriting for publishable output.
- Build → Sitemap: uses · Build flow generates site navigation metadata.
- Validate skills → Skills index: checks · Validation covers skill catalog structure.
- Run evals → Evals config: uses · Evaluation runner consumes scenario definitions.
- Validate skills → Run evals: complements · Validation and evals together gate content quality.
- Rewrite links → Skills index: prepares · Rewrites authored content for hosted consumption.
- Sitemap → Skills index: publishes · Sitemap is generated from the skill catalog.