Set up the Azure Cosmos DB Agent Kit

Install the Azure Cosmos DB Agent Kit to give your AI coding assistant guidance on data modeling, partition keys, queries, and SDK usage. Choose one installation method for your host, and then verify that the assistant can discover the installed skill.

Prerequisites

• An AI coding assistant that supports Agent Skills or one of the plugin formats listed in Agent Kit compatibility.
• Node.js with npm and npx installed if you use the skills CLI.
• Access to GitHub and the package registry used by your installation method.

You don't need an Azure subscription to install the skills or review code. Connecting separate tools to a database requires their own authentication and permissions. Don't include credentials or production data in setup prompts.

Install with the skills CLI

Use this method to select the skills and target assistants interactively:

npx skills add AzureCosmosDB/cosmosdb-agent-kit

Follow the CLI prompts to choose your target assistant and installation scope. Use your host's documented project or user-level scope, and avoid installing the same skill through multiple methods in the same host.

For host-specific installation methods, use one of the following options instead.

Install with an agent-specific method

These commands follow the Agent Kit installation instructions. Host versions and plugin availability can change. Check your host's prerequisites before installation.

Agent Package Manager (APM)

If you already use APM to manage agent dependencies, run:

apm install AzureCosmosDB/cosmosdb-agent-kit

GitHub Copilot CLI

In a Copilot CLI session, add the marketplace and install the plugin:

/plugin marketplace add AzureCosmosDB/cosmosdb-agent-kit
/plugin install cosmosdb@cosmosdb-agent-kit

Claude Code

In a Claude Code session, install from the official plugin marketplace:

/plugin install cosmosdb@claude-plugins-official

Gemini CLI

With Gemini CLI installed, run:

gemini extensions install https://github.com/AzureCosmosDB/cosmosdb-agent-kit

OpenAI Codex

Add the marketplace with the Codex CLI:

codex plugin marketplace add AzureCosmosDB/cosmosdb-agent-kit

Then install the Agent Kit from the Plugins Directory in the ChatGPT desktop app, as described in the repository's Codex instructions.

Grok Build

With Grok Build installed, add the marketplace, install the plugin, and inspect the discovered skills:

grok plugin marketplace add AzureCosmosDB/cosmosdb-agent-kit
grok plugin install cosmosdb --trust
grok inspect

The --trust option authorizes activation of the remote plugin. Review the source before trusting it.

Kimi Code CLI

In a Kimi Code CLI session, install from GitHub and reload:

/plugins install https://github.com/AzureCosmosDB/cosmosdb-agent-kit
/reload

Cursor and other Agent Skills-compatible hosts

Use the skills CLI and select your host. If you need a plugin-specific installation, consult the repository's plugin manifests and your host's current plugin instructions.

Verify skill discovery

1. If your host requires it, reload the assistant or start a new session after installation.

2. Open the project where you installed the skills. For user-level installations, confirm that your host can discover skills in that scope.

3. Check the host's installed skills or plugins view, if available, for cosmosdb-best-practices.

4. Try this prompt with a sanitized code sample or data model:

   Use the installed cosmosdb-best-practices skill to review my Azure Cosmos DB code.
   Identify the relevant guidance, explain your recommendations, and state what
   information you need before suggesting changes.
   

Check the host's skill-loading indicators or logs, if available. A response that mentions Azure Cosmos DB doesn't, by itself, prove that the skill loaded.

Troubleshoot installation

Symptom	What to check
npx isn't found.	Install Node.js with npm, then reopen your terminal so it picks up the updated path.
A plugin command isn't recognized.	Confirm that you're using the correct host and a version that supports the documented plugin method. Otherwise, use the skills CLI if your host supports Agent Skills.
Installation succeeds, but the skill isn't discovered.	Check the selected assistant, installation scope, workspace, and host trust settings. Reload the host if its instructions require it.
The assistant loads too much context.	Use on-demand skill loading or provide only task-relevant guidance. See context-loading considerations.
A registry or download request fails.	Read the command's error output and check network, proxy, and registry access before retrying.

AI tools

Connect your coding agent to Microsoft Learn or bring these installation instructions into your assistant.

For a compact index of the guides and their Markdown versions, use the Agent Kit documentation index (llms.txt). This index is a discovery aid, not a crawler policy or a guarantee that an assistant retrieves the articles.

Connect your AI agent
Set up Microsoft Learn MCP in Visual Studio Code.

Read as Markdown
Open a text version to copy into your assistant.

Ask ChatGPT
Get installation guidance for your coding assistant.

Ask Claude
Get installation guidance for your coding assistant.

The external links send only a public article URL and a generic prompt. You might need to sign in. If the assistant can't retrieve the article, copy the relevant Markdown text instead. These links don't install skills or grant database access.

Next step

Use the Agent Kit