agentsclimarketplace
Sign in

Cosmosdb best practices

Skill AzureCosmosDB/cosmosdb-agent-kit/skills/cosmosdb-best-practices

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.From its SKILL.md

Install
npx -y skills add AzureCosmosDB/cosmosdb-agent-kit --skill cosmosdb-best-practices

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

What its file declares

Copied from the file, not written here

The file declares its own license as MIT. That is the author’s claim about this one file, and it is not the same thing as the license GitHub reports for the repository, which is listed with the other numbers below.

SKILL.md

16.6 KB, ~3.8k tokens by cl100k_base, as published. Nobody here has run it

Azure Cosmos DB Best Practices

Comprehensive performance optimization guide for Azure Cosmos DB applications, containing 100+ rules across 12 categories, prioritized by impact to guide automated refactoring and code generation.

When to Apply

Reference these guidelines when:

  • Designing data models for Cosmos DB
  • Choosing partition keys
  • Writing or optimizing queries
  • Implementing SDK patterns
  • Using the Cosmos DB Emulator for local development
  • Inspecting or managing Cosmos DB data with developer tooling
  • Implementing vector search or RAG features on Cosmos DB
  • Reviewing code for performance issues
  • Configuring throughput and scaling
  • Building globally distributed applications

Rule Categories by Priority

PriorityCategoryImpactPrefix
1Data ModelingCRITICALmodel-
2Partition Key DesignCRITICALpartition-
3Query OptimizationHIGHquery-
4SDK Best PracticesHIGHsdk-
5Indexing StrategiesMEDIUM-HIGHindex-
6Throughput & ScalingMEDIUMthroughput-
7Global DistributionMEDIUMglobal-
8Monitoring & DiagnosticsLOW-MEDIUMmonitoring-
9Design PatternsHIGHpattern-
10Developer ToolingMEDIUMtooling-
11Vector SearchHIGHvector-

Quick Reference

1. Data Modeling (CRITICAL)

2. Partition Key Design (CRITICAL)

3. Query Optimization (HIGH)

4. SDK Best Practices (HIGH)

5. Indexing Strategies (MEDIUM-HIGH)

6. Throughput & Scaling (MEDIUM)

7. Global Distribution (MEDIUM)

8. Monitoring & Diagnostics (LOW-MEDIUM)

9. Design Patterns (HIGH)

10. Developer Tooling (MEDIUM)

11. Vector Search (HIGH)

12. Full-Text Search (HIGH)

  • fts-enable-capability - Enable EnableNoSQLFullTextSearch capability on the account — prerequisite for all FTS functions
  • fts-full-text-policy - Define fullTextPolicy on the container with correct language code (en-US, case-sensitive)
  • fts-index-policy - Add fullTextIndexes entry in the indexing policy to build the inverted index
  • fts-contains-query - Use FullTextContains / FullTextContainsAll / FullTextContainsAny instead of CONTAINS(LOWER(...))
  • fts-score-ranking - Use ORDER BY RANK FullTextScore(path, term) for BM25 relevance ranking
  • fts-hybrid-query - Combine FTS predicates with range/equality filters; put most selective filter first

How to Use

Use the linked rule files above for detailed explanations and code examples. The links give the agent direct paths to the relevant guidance instead of relying on folder scanning or inferred filenames.

Each rule file contains:

  • Brief explanation of why it matters
  • Incorrect code example with explanation
  • Correct code example with explanation
  • Additional context and references

What ships with it: 140 files

561.4 KB alongside SKILL.md

rules/

100 more files not listed here. See all 140 in the repository.

Gives 0 of the 12 instructions most performance cost skills give in ~3.8k tokens

Counted across 797 of the 1,117 authors here whose files we hold, read 2026-09-06

  • Check for product marketing context firstin 46 of 797, across 20 files
  • Measure before optimizingin 31 of 797, across 25 files
  • Profile first to identify the actual bottleneckin 23 of 797, across 22 files
  • Verify your robots.txt allows AI crawlersin 21 of 797, across 12 files
  • Import directly and avoid barrel filesin 19 of 797, across 15 files
  • Spawn all runs in the same turnin 18 of 797, across 11 files
  • Write a draft of the skillin 17 of 797, across 10 files
  • Understand the user's intentin 17 of 797, across 10 files
  • Use React.cache for per-request deduplicationin 16 of 797, across 11 files
  • Profile before optimizingin 16 of 797, across 14 files
  • Include specific numbers with sourcesin 15 of 797, across 8 files
  • Add lazy loading to below-fold imagesin 15 of 797, across 10 files

Said here and by no other author read

  • Exclude paths never queried
  • Use autoscale for variable workloads
  • Use Change Feed for cross-partition query optimization
  • Use VectorDistance for similarity search
  • Enable vector search on the account
  • Use point reads instead of queries

Grouped from the skills themselves: near-identical wordings counted once, and counted by distinct author, so one author publishing three of these counts once. Length counted with cl100k_base; the agent that loads this file may tokenize it differently.

Keep looking

Skills are one crate of 325,949. Ordering is by how many stacks a row turns up in, so the top of any crate is what has actually been picked rather than what has the most stars.