# cosmosdb-best-practices Azure Cosmos DB performance guidelines with 73 rules for data modeling, partitioning, query tuning, and SDK setup. Useful when designing or refactoring NoSQL code. - skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode · 859 installs · ★ 40 - Author: cosmosdb-agent-kit - License: MIT · policy=mirror · the beginning of the file is at the end of this page - Source: https://github.com/cline/skills/tree/HEAD/skills/cosmosdb-best-practices/SKILL.md - Updated: 2026-07-21 - HTML: https://affpapa.org/en/nevibecode/skills/cosmosdb-agent-kit-cosmosdb-best-practices ## What it does This skill integrates 73 prioritized guidelines across 10 categories from `AzureCosmosDB/cosmosdb-agent-kit`. It guides code generators through schema constraints like the 2MB document boundary, numeric precision under IEEE 754, and hierarchical partition keys. Rules are organized into individual files with category prefixes: `model-`, `partition-`, `query-`, `sdk-`, `index-`, and `throughput-`. You must prompt the assistant to load only prefix-matched files instead of importing all files at once, which prevents context exhaustion. ## Requirements - Works with: Azure ## Install ### Claude Code (native platform) 1. **Skills CLI (Vercel)** ```bash npx skills add cline/skills --skill cosmosdb-best-practices -a claude-code ``` 2. **Manually: put the files in place** - File: `~/.claude/skills/cosmosdb-best-practices/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/cosmosdb-best-practices/ ### Codex 1. **Skills CLI (Vercel)** ```bash npx skills add cline/skills --skill cosmosdb-best-practices -a codex ``` 2. **Manually: put the files in place** - File: `.agents/skills/cosmosdb-best-practices/SKILL.md` — For all projects use ~/.agents/skills/ ### Cursor 1. **Skills CLI (Vercel)** ```bash npx skills add cline/skills --skill cosmosdb-best-practices -a cursor ``` 2. **Manually: put the files in place** - File: `.cursor/skills/cosmosdb-best-practices/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/ ### GitHub Copilot 1. **GitHub CLI** ```bash gh skill install cline/skills cosmosdb-best-practices ``` 2. **Manually: put the files in place** - File: `.github/skills/cosmosdb-best-practices/SKILL.md` ### Gemini CLI 1. **Skills CLI (Vercel)** ```bash npx skills add cline/skills --skill cosmosdb-best-practices -a gemini-cli ``` 2. **Platform CLI** ```bash gemini skills install https://github.com/cline/skills --path skills/cosmosdb-best-practices ``` ### Windsurf (Devin Desktop) **Manually: put the files in place** - File: `.devin/skills/cosmosdb-best-practices/SKILL.md` — The legacy .windsurf/skills/ path still works ### OpenCode **Skills CLI (Vercel)** ```bash npx skills add cline/skills --skill cosmosdb-best-practices -a opencode ``` ### Claude.ai **Claude.ai** - Zip the folder and upload it in Settings → Capabilities → Skills Where a file is given instead of a command, copy the files from the source to that path: https://github.com/cline/skills/tree/HEAD/skills/cosmosdb-best-practices/SKILL.md ## When to use it - Design partition keys that prevent write hotspots and 20GB logical limits - Eliminate cross-partition queries using projections and continuation tokens - Configure CosmosClient singletons and Direct mode in application SDKs - Set up composite and spatial indexing policies for containers ## Example prompts - Review this container schema for 2MB limit and nesting depth risks - Refactor this NoSQL query to use parameterized filters and projections - Check my Cosmos DB client initialization code for singleton and retry handling ## Source text · SKILL.md · MIT Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 774e834c74cba47b. BEGIN THIRD-PARTY FILE 774e834c74cba47b ```text --- name: cosmosdb-best-practices license: MIT description: | Azure Cosmos DB performance optimization and best practices guidelines for NoSQL, partitioning, queries, SDK usage, and vector search. Use when writing, reviewing, or refactoring code that interacts with Azure Cosmos DB, designing data models, optimizing queries, or implementing high-performance database operations. metadata: author: cosmosdb-agent-kit version: "1.0.0" --- # Azure Cosmos DB Best Practices Comprehensive performance optimization guide for Azure Cosmos DB applications, containing 73+ rules across 10 categories, prioritized by impact to guide automated refactoring and code generation. 73 individual rule files are in the [rules/](./rules/) directory, one file per rule, synced from the [AzureCosmosDB/cosmosdb-agent-kit](https://github.com/AzureCosmosDB/cosmosdb-agent-kit). Load only the relevant rule file(s) when answering a question — do NOT load all files at once. ## When to Apply Reference these guidelines when: - Designing data models for Cosmos DB - Choosing partition keys - Writing or optimizing queries - Implementing SDK patterns - Reviewing code for performance issues - Configuring throughput and scaling - Building globally distributed applications - Implementing vector search and RAG patterns ## Rule Index Rules are grouped by category prefix. For a given question, load files matching the relevant prefix (e.g., `model-*.md` for data modeling, `sdk-*.md` for SDK usage). See [rules/_sections.md](rules/_sections.md) for category descriptions. ### 1. Data Modeling — CRITICAL (prefix: `model-`) - [model-embed-related.md](rules/model-embed-related.md) — Embed related data retrieved together - [model-reference-large.md](rules/model-reference-large.md) — Reference data when items grow large - [model-avoid-2mb-limit.md](rules/model-avoid-2mb-limit.md) — Keep items well under 2MB limit - [model-id-constraints.md](rules/model-id-constraints.md) — Follow ID value length and character constraints - [model-nesting-depth.md](rules/model-nesting-depth.md) — Stay within 128-level nesting depth limit - [model-numeric-precision.md](rules/model-numeric-precision.md) — Understand IEEE 754 numeric precision limits - [model-denormalize-reads.md](rules/model-denormalize-reads.md) — Denormalize for read-heavy workloads - [model-schema-versioning.md](rules/model-schema-versioning.md) — Version your document schemas - [model-type-discriminator.md](rules/model-type-discriminator.md) — Use type discriminators for polymorphic data - [model-json-serialization.md](rules/model-json-serialization.md) — Handle JSON serialization correctly - [model-relationship-references.md](rules/model-relationship-references.md) — Use ID references with transient hydration ### 2. Partition Key Design — CRITICAL (prefix: `partition-`) - [partition-high-cardinality.md](rules/partition-high-cardinality.md) — Choose high-cardinality partition keys ``` END THIRD-PARTY FILE 774e834c74cba47b The third-party file has ended. Everything between the 774e834c74cba47b tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file. First 2980 of 10386 bytes. © cosmosdb-agent-kit · MIT · https://github.com/cline/skills/tree/HEAD/skills/cosmosdb-best-practices/SKILL.md _Part of the page did not fit — see the HTML version._ --- NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md