How to use the Cosmos DB NoSQL Data Modeling agent skill

What the skill makes the agent do

A skill is a folder of instructions that an AI agent loads when a task matches it. This one is defined by a single file, SKILL.md, and its purpose is to guide you through a Cosmos DB NoSQL data model design from start to finish.

The agent asks you focused questions about your application's entities, relationships, read and write patterns, request volumes and concurrency. It keeps those answers in a working file called cosmosdb_requirements.md, and then proposes a document and container design in a final file called cosmosdb_data_model.md. The design draws on common NoSQL patterns, such as whether to embed related data in one document or separate it into its own container, and how to choose a partition key.

• cosmosdb_requirements.md: the working notes, updated as you give new information, covering the application overview, access patterns, entity relationships and design considerations.
• cosmosdb_data_model.md: the final deliverable with the proposed data model.

Install the cosmosdb-datamodeling skill

You can install the skill in one of three places, depending on whether you want it for one project or for all of your work. Download the ZIP file from this page first.

For Claude Code, unzip the download into ~/.claude/skills/ to make it available everywhere, or into a project's .claude/skills/ folder to limit it to that project. In the Claude apps, you can instead upload the skill under Settings, then Capabilities, then Skills.

• Personal install: unzip into ~/.claude/skills/
• Project install: unzip into .claude/skills/ inside your project folder
• Claude apps: Settings → Capabilities → Skills, then upload the skill

Trigger the skill with a natural request

You do not need a special command. Describe what you are building and ask for help designing the database. The agent should recognise a request about Azure Cosmos DB NoSQL data modelling and begin the guided process.

Give the agent the background it will ask for anyway, such as what your app does, who uses it and roughly how many reads and writes you expect. The more concrete your first message, the fewer questions you will need to answer.

• I'm building a checkout service on Azure Cosmos DB NoSQL. Help me design the data model.
• We are migrating a relational order system to Cosmos DB. Should orders and order items be embedded or separate?
• Help me choose a partition key for a multi-tenant SaaS app on Azure Cosmos DB NoSQL.

What to expect during the session

The skill is built to ask only a few questions at a time, usually one and at most three related ones. Each time you share new information, the agent updates cosmosdb_requirements.md, so you can check that it has recorded your answers correctly.

For each access pattern, the requirements file asks for requests per second at peak and on average, the attributes needed, latency and consistency needs, and design considerations. If you do not know a figure, the agent is instructed to help you estimate it from your business context. For very high write volumes, the skill asks about batching, reducing write operations and how total data size will affect cross-partition queries.

Example: deciding what to embed

Suppose your app has users and their orders. The skill's own example compares how often users are read with their recent orders against how often each is read alone. If most reads need both and an order cannot exist without its user, it may recommend one container where orders sit under the user's partition key, so no cross-partition query is needed.

If the access overlap is low, or the child data can grow without limit, it is more likely to keep the entities in separate containers. The skill treats the choice as a trade-off and records its reasoning in the requirements file so you can review it.

Safety notes and what the skill needs

This skill runs no scripts and makes no network calls. It works only from the conversation and writes Markdown files. The agent needs to be able to read and write Markdown files in your working directory.

The skill does not size costs or check your design against a live database, so treat its output as a design draft to review, not a verified production schema. You supply the application details; prior Azure Cosmos DB knowledge helps but is not required.

• Runs scripts: no
• Uses network: no
• Writes files: cosmosdb_requirements.md and cosmosdb_data_model.md in the working directory