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.
| 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 for the agent (triggers activation)AGENTS.md- Compiled rules (what agents read)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 Waza 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 waza (one-time)
irm https://raw.githubusercontent.com/microsoft/waza/main/install.ps1 | iex # Windows
curl -fsSL https://raw.githubusercontent.com/microsoft/waza/main/install.sh | bash # macOS/Linux
# Run evaluations
waza run evals/cosmosdb-best-practices/eval.yaml -v
# Check skill readiness
waza 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 Waza to evaluate skill quality — testing that the agent produces correct Cosmos DB guidance across data modeling, partitioning, queries, SDK usage, and throughput scenarios.
# Install waza
irm https://raw.githubusercontent.com/microsoft/waza/main/install.ps1 | iex # Windows
curl -fsSL https://raw.githubusercontent.com/microsoft/waza/main/install.sh | bash # macOS/Linux
# Run evaluations (mock executor, no API key needed)
waza run evals/cosmosdb-best-practices/eval.yaml -v
# Check skill readiness
waza check skills/cosmosdb-best-practices
# Run with a real model (requires Copilot auth)
waza 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