A collection of skills for AI coding agents working with Azure Cosmos DB. Skills are packaged instructions and scripts that extend agent capabilities.
Skills follow the Agent Skills format and the kit ships with plugin manifests for Claude Code, Codex, Cursor, Gemini CLI, and GitHub Copilot.
This agent kit is designed for progressive (on-demand) skill delivery: hosts that load a relevant skill only when it is needed, rather than injecting the entire skill set into every prompt. For the best results:
- Recommended: Agent hosts that support progressive or on-demand skill loading (for example, GitHub Copilot in VS Code), or models with a large context window (roughly 200K+ tokens).
- Use with caution: Hosts that inject the entire skill set as always-on context (some IDE agents and CLI tools) combined with models that have a smaller usable prompt budget (roughly 128K tokens or less). In this configuration the full skill payload can consume, or overflow, the context window, which degrades output quality or causes the agent to stop making progress.
If you are in a constrained setup (always-on injection plus a smaller-context model), prefer one of the following:
- Load a single, focused skill for the task at hand instead of the full set, or
- Switch to a larger-context model, or
- Use a host that supports on-demand skill discovery.
These recommendations are based on internal skill-efficacy testing across multiple models and delivery mechanisms. Exact context limits vary by model and host.
| Skill | Description | Status |
|---|---|---|
| cosmosdb-best-practices | Performance optimization (111 rules, 12 categories) | ✅ Stable |
| migration-capacity-planning | RU calculation, data sizing, pre-split partitions | 🚧 Planned |
Azure Cosmos DB performance optimization guidelines containing 111 rules across 12 categories, prioritized by impact.
Use when:
- Writing new code that interacts with Cosmos DB
- Designing data models or choosing partition keys
- Reviewing code for performance issues
- Optimizing queries or throughput configuration
Categories covered:
- Data Modeling (Critical)
- Partition Key Design (Critical)
- Query Optimization (High)
- SDK Best Practices (High)
- Design Patterns (High)
- Vector Search (High)
- Full-Text Search (High)
- Security (High)
- Indexing Strategies (Medium-High)
- Throughput & Scaling (Medium)
- Global Distribution (Medium)
- Developer Tooling (Medium)
- Monitoring & Diagnostics (Low-Medium)
apm install AzureCosmosDB/cosmosdb-agent-kitInstalls the skill across GitHub Copilot, Claude Code, Cursor, Codex, and Gemini in one command.
npx skills add AzureCosmosDB/cosmosdb-agent-kitThis drops the skill catalog into whichever agent you're using.
/plugin marketplace add AzureCosmosDB/cosmosdb-agent-kit
/plugin install cosmosdb@cosmosdb-agent-kit
/plugin install cosmosdb@claude-plugins-official
gemini extensions install https://github.com/AzureCosmosDB/cosmosdb-agent-kitThe repository includes ready-made plugin manifests:
| Agent | Manifest |
|---|---|
| Claude Code | .claude-plugin/plugin.json |
| OpenAI Codex | .codex-plugin/plugin.json |
| Cursor | .cursor-plugin/plugin.json |
| Gemini CLI | gemini-extension.json + GEMINI.md |
| GitHub Copilot | skills/cosmosdb-best-practices/SKILL.md (auto-detected) |
A project website is available in docs/ and is designed for GitHub Pages publishing.
- Main page:
docs/index.html - Styles:
docs/styles.css - Interactions + survey flow:
docs/app.js
The website includes a feedback survey that opens a prefilled GitHub issue so users can share improvements for Agent Kit without requiring a backend service.
# Option 1: VS Code Live Server
# open docs/index.html with Live Server
# Option 2: Python static server
python -m http.server 8080 --directory docsThen open http://localhost:8080.
In repository settings, set Pages source to Deploy from a branch, branch main, folder /docs.
Skills are automatically available once installed. The agent will use them when relevant tasks are detected.
Examples:
Review my Cosmos DB data model
Help me choose a partition key for my orders collection
Optimize this Cosmos DB query
Each skill contains:
SKILL.md- Instructions and index for the agent (what agents read; links to rules)rules/- Individual rule filesmetadata.json- Version and metadata
Works with Claude Code, Codex, Cursor, Gemini CLI, GitHub Copilot, and other Agent Skills-compatible tools.
See CONTRIBUTING.md for contribution guidelines.
This project includes a Vally eval framework for local skill testing. Evals are not enforced in CI today (the mock executor cannot validate response content), but you can run them locally to sanity-check your changes:
# Install Vally by following the instructions at https://github.com/microsoft/vally
# Run evaluations
vally run evals/cosmosdb-best-practices/eval.yaml -v
# Check skill readiness
vally check skills/cosmosdb-best-practicesLooking for a way to help? Check out our good first issues or browse the Discussions board to share ideas.
Thanks to everyone who has contributed rules, fixes, and ideas!
Contributions of any kind welcome! See the contributing guide to get started.
This project uses Vally to evaluate skill quality, testing that the agent produces correct Cosmos DB guidance across data modeling, partitioning, queries, SDK usage, and throughput scenarios.
# Install Vally by following the instructions at https://github.com/microsoft/vally
# Run evaluations (mock executor, no API key needed)
vally run evals/cosmosdb-best-practices/eval.yaml -v
# Check skill readiness
vally check skills/cosmosdb-best-practices
# Run with a real model (requires Copilot auth)
vally run evals/cosmosdb-best-practices/eval.yaml --executor copilot-sdk --model claude-sonnet-4.6See CHANGELOG.md for a dated history of updates to the agent kit, including the cosmosdb-best-practices skill and the testing framework. Each entry links to the PR that introduced the change.
When you merge a PR, add a new dated entry at the top of CHANGELOG.md.
MIT