Official agent skill

Cosmosdb Best Practices

by microsoft in microsoft/vscode-cosmosdb

Azure Cosmos DB performance optimization and best practices guidelines for NoSQL, partitioning, queries, and SDK usage.

OfficialMITAuto-check passedDatabases

Install Cosmosdb Best Practices

skills CLI
$ npx skills add microsoft/vscode-cosmosdb --skill cosmosdb-best-practices -a claude-code

Project install by default; add -g for ~/.claude/skills/.

GitHub CLI
$ gh skill install microsoft/vscode-cosmosdb cosmosdb-best-practices --agent claude-code

Project scope by default; add --scope user for a personal install. Needs GitHub CLI 2.90.0 or later (public preview).

Manual copy
$ git clone --depth 1 https://github.com/microsoft/vscode-cosmosdb.git skills-src && mkdir -p .claude/skills && cp -r skills-src/skills/cosmosdb-best-practices .claude/skills/cosmosdb-best-practices && rm -rf skills-src

Use ~/.claude/skills/ instead of .claude/skills for a personal install. The folder must contain SKILL.md.

Claude Code skills documentation · loads skills from .claude/skills/

Facts

Skill name
cosmosdb-best-practices
GitHub stars
200
Token cost
~4.3k tokens
SKILL.md length
1,194 words
Files
137
Skills in repo
6
Repo updated
First seen
Licence
MIT

At a glance

Azure Cosmos DB performance optimization and best practices guidelines for NoSQL, partitioning, queries, and SDK usage.

  • Works in 12 steps: Data Modeling (CRITICAL) → Partition Key Design (CRITICAL) → Query Optimization (HIGH) → …
  • Refactoring code that interacts with Azure Cosmos DB
  • SKILL.md covers When to Apply, Rule Categories by Priority, Quick Reference and How to Use
  • Instructions only: no scripts, shell commands, URLs or credentials in SKILL.md

What it does

Cosmosdb Best Practices is an agent skill from microsoft/vscode-cosmosdb, published by the product's own GitHub organization. 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…

Its SKILL.md is about 4.3k tokens, which your agent loads only when the skill is triggered. The skill folder holds 137 other files (for example `rules/fts-add-index.md`, `rules/fts-define-policy.md` and `rules/fts-enable-capability.md`).

It sits in Databases, covering NoSQL databases and Search implementation. It works with Azure Cosmos DB, Microsoft Azure, Microsoft SQL Server and MongoDB. The repository describes itself as: Azure Cosmos DB extension for VS Code. The licence is MIT.

When your agent uses it

  • Refactoring code that interacts with Azure Cosmos DB
  • Designing data models
  • Optimizing queries
  • Implementing high-performance database operations

Example prompts

  • “/cosmosdb-best-practices”

Requirements

  • Python 3

Workflow steps

12 steps, taken from the step headings in SKILL.md.

  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)

What it can do on your machine

Read from SKILL.md and the folder at commit cf3dbf8. It shows what the files ask for, not the result of running them.

  • Tool permissions

    Pre-approves nothing: there is no allowed-tools line, so your agent's usual permission prompts apply.

    From allowed-tools in the SKILL.md frontmatter.

  • Runs code

    No scripts in the folder and no shell commands in SKILL.md.

    From the folder's file list and the shell code blocks in SKILL.md.

  • Network

    No URLs in SKILL.md.

    From URLs in SKILL.md, links to its own repository left out.

  • Credentials

    Names no API keys, tokens, secrets or passwords.

    From names ending in _API_KEY, _TOKEN, _SECRET, _KEY or _PASSWORD in SKILL.md.

Context cost

Cosmosdb Best Practices loads about 4.3k tokens when it runs. Until then it costs about 211 tokens; SKILL.md has 1,194 words of instructions outside code blocks.

Always · name and description, kept in context so the agent knows when to use it
~211
When it runs · the whole SKILL.md, loaded when a task matches
~4.3k

Estimates: characters ÷ 4, the usual rule of thumb; real counts depend on the model's tokenizer. Scripts and assets cost tokens only if the agent reads them.

Safety

Auto-check passed

The automated check found no risky patterns in SKILL.md.

Automated static check — not a guarantee. Review scripts before installing. It scans the text of SKILL.md for risky patterns (piping downloads into a shell, reading credential files, hidden Unicode, destructive commands); files beside SKILL.md are not scanned.

SKILL.md

The full file from microsoft/vscode-cosmosdb at commit cf3dbf8, republished under its MIT licence (© microsoft). 1,194 words, ~4,252 tokens.

Download SKILL.mdSave it as .claude/skills/cosmosdb-best-practices/SKILL.md (or your agent's skills folder). This skill also uses 136 other files; get the full folder from GitHub.
name
cosmosdb-best-practices
description
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.
license
MIT
metadata.author
cosmosdb-agent-kit
metadata.version
1.0.0

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)
Show full SKILL.md (459 more words)Show less
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

© microsoft, MIT. Rendered from Markdown: HTML in the file is shown as text, images as links, and headings moved down two levels. Raw file

Files

SKILL.md and 136 other files in skills/cosmosdb-best-practices of microsoft/vscode-cosmosdb.

  • SKILL.md
  • rules/fts-add-index.md
  • rules/fts-define-policy.md
  • rules/fts-enable-capability.md
  • rules/fts-hybrid-queries.md
  • rules/fts-keyword-matching.md
  • rules/fts-relevance-ranking.md
  • rules/global-conflict-resolution.md
  • rules/global-consistency.md
  • rules/global-failover.md
  • rules/global-multi-region-write-antipattern.md
  • rules/global-multi-region.md
  • rules/global-read-regions.md
  • rules/global-zone-redundancy.md
  • rules/index-composite-direction.md
  • rules/index-composite.md
  • rules/index-exclude-unused.md
  • rules/index-lazy-consistent.md
  • rules/index-path-syntax.md
  • rules/index-range-vs-hash.md
  • … and 117 more

Open the folder on GitHubat commit cf3dbf8

Compare with similar skills

Cosmosdb Best Practices next to the 5 skills that share the most tags, products or categories with it. Stars are the repository's; “used in” counts other GitHub owners with a copy.

Cosmosdb Best Practices compared with similar skills
SkillStarsUsed inTokensAuto-checkLicenceRepo updated
Cosmosdb Best Practices this skillmicrosoft/vscode-cosmosdb200—~4.3kAutomated safety check: PassMIT
Azure Database MigrationMicrosoftDocs/Agent-Skills777—~1.4kAutomated safety check: PassCC-BY-4.0
Whodbxiaoyuge886/aigc198—~894Automated safety check: PassMIT
Azure Cosmos DB Pymicrosoft/skills3.1k—~2.8kAutomated safety check: PassMIT
Svc Databases0ld13rr/pentestcode828—~379Automated safety check: PassMIT
Azure Cosmos Pymicrosoft/skills3.1k—~2.3kAutomated safety check: PassMIT

Similar skills

  • Azure Database Migration

    MicrosoftDocs/Agent-Skills

    Official

    Expert knowledge for Azure Database Migration Service development including troubleshooting, decision making, limits & quotas, security, integrations & coding patterns, and deployment.

    777 GitHub stars~1.4k tokensUpdated 3 days ago
    DatabasesAuto-check passed
  • Whodb

    xiaoyuge886/aigc

    Database operations including querying, schema exploration, and data analysis.

    198 GitHub stars~894 tokensUpdated 2 mo ago
    DatabasesAuto-check passed
  • Azure Cosmos DB Py

    microsoft/skills

    Official

    Build Azure Cosmos DB NoSQL services with Python/FastAPI following production-grade patterns.

    3.1k GitHub stars~2.8k tokensUpdated today
    DatabasesAuto-check passed
  • Svc Database

    s0ld13rr/pentestcode

    Database RCE paths — UDF, xpcmdshell, COPY TO PROGRAM, Redis key write.

    828 GitHub stars~379 tokensUpdated 7 days ago
    DatabasesAuto-check passed
  • Azure Cosmos Py

    microsoft/skills

    Official

    Azure Cosmos DB SDK for Python (NoSQL API). An agent skill from microsoft/skills.

    3.1k GitHub stars~2.3k tokensUpdated today
    DatabasesAuto-check passed
  • Azure Data Tables Py

    microsoft/skills

    Official

    Azure Tables SDK for Python (Storage and Cosmos DB). An agent skill from microsoft/skills.

    3.1k GitHub stars~2.1k tokensUpdated today
    DatabasesAuto-check passed

More from microsoft/vscode-cosmosdb

  • Accessibility Aria Expert

    microsoft/vscode-cosmosdb

    Official

    Detects and fixes accessibility issues in React/Fluent UI webviews.

    200 GitHub stars~3.2k tokensUpdated today
    Auto-check passed
  • Telemetry Best Practices

    microsoft/vscode-cosmosdb

    Official

    Reviews and authors telemetry code in this extension. An agent skill from microsoft/vscode-cosmosdb.

    200 GitHub stars~3.6k tokensUpdated today
    Auto-check passed
  • Backport

    microsoft/vscode-cosmosdb

    Official

    Backport changes (current branch, a PR, a branch, or specific commits/SHAs) onto a target branch (typically a release branch like rel/).

    200 GitHub stars~5k tokensUpdated today
    Auto-check passed
  • Cosmosdb Nosql Query Generation

    microsoft/vscode-cosmosdb

    Official

    Generate, explain, edit, and fix Azure Cosmos DB for NoSQL (SQL API) queries.

    200 GitHub stars~4k tokensUpdated today
    Auto-check: warnings
  • Cosmosdb Nosql Query Editor

    microsoft/vscode-cosmosdb

    Official

    Drive the active Azure Cosmos DB for NoSQL Query Editor in VS Code from natural language.

    200 GitHub stars~1.1k tokensUpdated today
    Auto-check: warnings

Categories

Questions about Cosmosdb Best Practices

What does Cosmosdb Best Practices do?

Azure Cosmos DB performance optimization and best practices guidelines for NoSQL, partitioning, queries, and SDK usage. Cosmosdb Best Practices is an agent skill from microsoft/vscode-cosmosdb, published by the product's own GitHub organization. Azure Cosmos DB performance optimization and best practices guidelines for NoSQL, partitioning, queries, and SDK usage.

When should I use Cosmosdb Best Practices?

Cosmosdb Best Practices fits situations like: refactoring code that interacts with Azure Cosmos DB; designing data models; optimizing queries; implementing high-performance database operations.

How do I install Cosmosdb Best Practices in Claude Code?

Run `npx skills add microsoft/vscode-cosmosdb --skill cosmosdb-best-practices -a claude-code`. Or copy the skill folder (skills/cosmosdb-best-practices in microsoft/vscode-cosmosdb) into .claude/skills/cosmosdb-best-practices in your project. Claude Code loads it when a task matches its description.

How do I install Cosmosdb Best Practices in Codex?

Run `npx skills add microsoft/vscode-cosmosdb --skill cosmosdb-best-practices -a codex`. Or copy the skill folder (skills/cosmosdb-best-practices in microsoft/vscode-cosmosdb) into .agents/skills/cosmosdb-best-practices in your project. Codex loads it when a task matches its description.

Can I use Cosmosdb Best Practices in Cursor, Gemini CLI or GitHub Copilot?

Cursor, Gemini CLI, GitHub Copilot and OpenCode also load SKILL.md folders. With the skills CLI, run `npx skills add microsoft/vscode-cosmosdb --skill cosmosdb-best-practices -a cursor` (or -a gemini-cli, github-copilot or opencode for the others). To copy it by hand, put the folder in .cursor/skills/cosmosdb-best-practices, .gemini/skills/cosmosdb-best-practices, .github/skills/cosmosdb-best-practices and .opencode/skills/cosmosdb-best-practices in your project.

What does Cosmosdb Best Practices need to run?

SKILL.md names no scripts, command-line tools or credentials: Cosmosdb Best Practices is instructions for the agent only. Our summary lists: Python 3.

Does Cosmosdb Best Practices access the network?

SKILL.md contains no URLs. Any network use would come from the scripts or tools the agent runs. This is read from the text; nothing was executed.

Is Cosmosdb Best Practices safe to install?

Our automated static check of SKILL.md found no risky patterns, such as piping downloads into a shell, reading credential files or hidden Unicode. It is not a guarantee. Review the folder before installing.

What licence does Cosmosdb Best Practices use?

Cosmosdb Best Practices is published under the MIT licence (declared in SKILL.md). It allows redistribution, so the full SKILL.md is shown on this page.

How many tokens does Cosmosdb Best Practices use?

About 4.3k tokens (SKILL.md is roughly 17k characters). Agents keep only the skill's name and description in context until a task matches; then they load SKILL.md in full.

What are the alternatives to Cosmosdb Best Practices?

Skills that share tags, products or a category with Cosmosdb Best Practices: Azure Database Migration (MicrosoftDocs/Agent-Skills, 777 stars), Whodb (xiaoyuge886/aigc, 198 stars), Azure Cosmos DB Py (microsoft/skills, 3.1k stars) and Svc Database (s0ld13rr/pentestcode, 828 stars). The comparison table on this page puts their stars, adoption, token cost, safety result and licence side by side.

Who maintains Cosmosdb Best Practices?

microsoft (a GitHub organization, an official publisher) maintains it in microsoft/vscode-cosmosdb, which has 200 GitHub stars. The repository holds 6 skills in this directory. The repository was last updated on October 9, 2026.

Source: microsoft/vscode-cosmosdb on GitHub. Facts on this page come from the repository at the commit we read; the author's words are quoted as theirs.