Design, optimize, secure, and globally scale Azure Cosmos DB for NoSQL—covering data modeling, partition keys, indexing, vector/full-text search, query and SDK best practices, throughput planning, monitoring, and developer tooling with VS Code and Emulator.
Azure Cosmos DB performance optimization and best practices guidelines for NoSQL, partitioning, queries, and SDK usage. Use when writing, reviewing, or refactoring code that interacts with Azure Cosmos DB, designing data models, optimizing queries, or implementing high-performance database operations. USE FOR: Cosmos DB NoSQL, partition key design, RU optimization, point reads, cross-partition queries, SDK singleton, CosmosClient, container modeling, change feed, bulk operations, vector search, full-text search, hierarchical partition keys, global distribution, autoscale throughput, indexing policy. DO NOT USE FOR: PostgreSQL, MySQL, MongoDB (non-Azure), DynamoDB, Cassandra, Azure SQL, Cosmos DB for PostgreSQL (vCore), Cosmos DB for MongoDB vCore, Azure DocumentDB, general SQL databases, Redis, Elasticsearch.
Azure Cosmos DB data modeling best practices: embedding vs referencing, document size limits, schema versioning, type discriminators, JSON serialization, denormalization, and relationship patterns. USE FOR: Cosmos DB document design, embedding related data, referencing large data, 2MB item limit, nesting depth, numeric precision, denormalize reads, schema versions, type discriminator, polymorphic containers, JSON serialization, relationship references. DO NOT USE FOR: partition key design (use cosmosdb-partition-key), query optimization (use cosmosdb-query-optimization), SDK client code (use cosmosdb-sdk).
Azure Cosmos DB design patterns: change feed materialized views, efficient ranking, service layer relationship hydration, LangGraph multi-agent orchestration, human-in-the-loop interrupts, checkpoint resumption, agent routing, FastAPI startup, chat history separation, background task writes, async Cosmos DB routing, and agent name attribution. USE FOR: Cosmos DB change feed, materialized views, CQRS, event sourcing, ranking patterns, service layer, relationship hydration, LangGraph, multi-agent, human-in-the-loop, interrupt, checkpoint, agent routing, FastAPI startup, chat history, background tasks, async routing, agent attribution, AI grounding. DO NOT USE FOR: SDK configuration (use cosmosdb-sdk), data modeling (use cosmosdb-data-modeling).
Azure Cosmos DB full-text search best practices: enabling the capability flag, defining fullTextPolicy, configuring fullTextIndexes, keyword matching with FullTextContains functions, BM25 relevance ranking, and hybrid queries. USE FOR: Cosmos DB full-text search, FTS, EnableNoSQLFullTextSearch, fullTextPolicy, fullTextIndexes, FullTextContains, FullTextContainsAll, FullTextContainsAny, FullTextScore, BM25 ranking, RANK, hybrid queries, keyword search, inverted index, language-aware tokenization. DO NOT USE FOR: vector search (use cosmosdb-vector-search), regular query optimization (use cosmosdb-query-optimization).
Azure Cosmos DB global distribution best practices: multi-region writes, consistency levels, conflict resolution, automatic failover, read regions, and zone redundancy for high availability. USE FOR: Cosmos DB multi-region, consistency levels, strong consistency, bounded staleness, session consistency, eventual consistency, conflict resolution, automatic failover, read regions, zone redundancy, global replication, disaster recovery, geo-redundancy, multi-master. DO NOT USE FOR: SDK preferred regions (use cosmosdb-sdk), monitoring (use cosmosdb-monitoring).
Own this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge. GitHub access is read-only (username + org membership).
Sign in to claimOwn this plugin?
Verify ownership to unlock analytics, metadata editing, and a verified badge. GitHub access is read-only (username + org membership).
Sign in to claimBased on adoption, maintenance, documentation, and repository signals. Not a security audit or endorsement.
A collection of skills for AI coding agents working with Azure Cosmos DB. Skills are packaged instructions and scripts that extend agent capabilities.
Skills follow the Agent Skills format and the kit ships with plugin manifests for Claude Code, Codex, Cursor, Gemini CLI, and GitHub Copilot.
| Skill | Description | Status |
|---|---|---|
| cosmosdb-best-practices | Performance optimization (111 rules, 12 categories) | ✅ Stable |
| migration-capacity-planning | RU calculation, data sizing, pre-split partitions | 🚧 Planned |
Azure Cosmos DB performance optimization guidelines containing 111 rules across 12 categories, prioritized by impact.
Use when:
Categories covered:
apm install AzureCosmosDB/cosmosdb-agent-kit
Installs the skill across GitHub Copilot, Claude Code, Cursor, Codex, and Gemini in one command.
npx skills add AzureCosmosDB/cosmosdb-agent-kit
This drops the skill catalog into whichever agent you're using.
/plugin marketplace add AzureCosmosDB/cosmosdb-agent-kit
/plugin install cosmosdb@cosmosdb-agent-kit
/plugin install cosmosdb@claude-plugins-official
gemini extensions install https://github.com/AzureCosmosDB/cosmosdb-agent-kit
The repository includes ready-made plugin manifests:
| Agent | Manifest |
|---|---|
| Claude Code | .claude-plugin/plugin.json |
| OpenAI Codex | .codex-plugin/plugin.json |
| Cursor | .cursor-plugin/plugin.json |
| Gemini CLI | gemini-extension.json + GEMINI.md |
| GitHub Copilot | skills/cosmosdb-best-practices/SKILL.md (auto-detected) |
A project website is available in docs/ and is designed for GitHub Pages publishing.
docs/index.htmldocs/styles.cssdocs/app.jsThe website includes a feedback survey that opens a prefilled GitHub issue so users can share improvements for Agent Kit without requiring a backend service.
# Option 1: VS Code Live Server
# open docs/index.html with Live Server
# Option 2: Python static server
python -m http.server 8080 --directory docs
Then open http://localhost:8080.
In repository settings, set Pages source to Deploy from a branch, branch main, folder /docs.
Skills are automatically available once installed. The agent will use them when relevant tasks are detected.
Examples:
Review my Cosmos DB data model
Help me choose a partition key for my orders collection
Optimize this Cosmos DB query
Each skill contains:
SKILL.md - Instructions for the agent (triggers activation)AGENTS.md - Compiled rules (what agents read)rules/ - Individual rule filesmetadata.json - Version and metadataWorks with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and other Agent Skills-compatible tools.
See CONTRIBUTING.md for contribution guidelines.
This project includes a Waza eval framework for local skill testing. Evals are not enforced in CI today (the mock executor cannot validate response content), but you can run them locally to sanity-check your changes:
Azure Cosmos DB plugin for Claude Code. Includes 73 best-practice rules across 10 categories covering data modeling, partition key design, query optimization, SDK usage, indexing, throughput management, global distribution, monitoring, design patterns, and vector search. No external services or configuration required. Optional MCP Toolkit integration available for live database operations.
npx claudepluginhub azurecosmosdb/cosmosdb-agent-kit --plugin azure-cosmosdbDatabase plugin for nosql-data-modeler
Use this agent when you need to optimize database performance for B2B applications at enterprise scale. This agent specializes in multi-tenant database optimization, query performance tuning, indexing strategies, connection pooling, and database scaling for SaaS platforms. Handles PostgreSQL, MySQL, MongoDB, and cloud database optimizations. Examples:
Comprehensive T-SQL and SQL Server expertise for query optimization, performance tuning, and Azure SQL Database. PROACTIVELY activate for: (1) T-SQL query optimization and SARGability analysis, (2) SQL Server performance tuning, (3) Index design and strategy, (4) Execution plan analysis, (5) Parameter sniffing solutions, (6) Azure SQL Database optimization, (7) Window functions and advanced patterns, (8) Columnstore and In-Memory OLTP, (9) Query Store and IQP features. Includes: tsql-expert agent, 5 progressive disclosure skills, 3 optimization commands, diagnostic scripts.
Create, connect, and interact with a Cloud SQL for PostgreSQL database and data.
Official MongoDB agent skills for schema design, query tuning, search, and connections.
Create, connect, and interact with an AlloyDB for PostgreSQL database and data.