Open Source • Agent Skills Format

# Azure Cosmos DB
Agent Kit

Teaching AI coding agents Cosmos DB best practices —
so every line of generated code is production-ready.

github.com/AzureCosmosDB/cosmosdb-agent-kit | MIT License

## The Problem

### AI Agents Are Writing Database Code

- Copilot, Claude, Gemini generate Cosmos DB apps daily
- They lack deep knowledge of partitioning, RU costs, SDK quirks
- Result: hot partitions, cross-partition scans, missing retries
- Bugs surface at scale, not during development

### Real Failures We've Seen

- `SELECT TOP @top` — doesn't work (must be literal)
- Composite index directions don't match ORDER BY
- Missing `aiohttp` for Python async SDK
- Wrong ETag API usage per language SDK
- No cascade delete of denormalized documents

## What Is the Agent Kit?

A collection of skills that plug into AI coding agents — giving them expert-level Cosmos DB knowledge at code-generation time.

75+
Best Practice Rules
11
Categories
5
Test Scenarios
7+
Compatible Agents

Follows the open Agent Skills standard (agentskills.io) — install once, works across Copilot, Claude Code, Gemini CLI, and more.

## How It Works

Step 1
Install Skill
→
Step 2
Agent Detects
Cosmos DB Task
→
Step 3
Loads SKILL.md
as Index
→
Step 4
Reads Relevant
Rule Files
→
Step 5
Generates
Optimized Code
# One command to install
npx skills add AzureCosmosDB/cosmosdb-agent-kit
# Then just ask your agent naturally:
"Help me choose a partition key for my orders collection"
"Optimize this Cosmos DB query"
"Review my Cosmos DB data model"

## Rule Categories by Impact

# | Category | Impact | Example Rule
--- | --- | --- | ---
1 | Data Modeling | Critical | Embed related data retrieved together
2 | Partition Key Design | Critical | Choose high-cardinality, immutable keys
3 | Query Optimization | High | Use point reads when id + PK are known
4 | SDK Best Practices | High | Singleton CosmosClient, async APIs
5 | Indexing Strategies | Medium-High | Composite indexes matching ORDER BY
6 | Throughput & Scaling | Medium | Autoscale for variable workloads
7 | Global Distribution | Medium | Multi-region writes, failover config
8 | Monitoring | Low-Med | Track RU consumption, P99 latency
9 | Design Patterns | High | Change Feed materialized views
10 | Vector Search | High | Embedding policy + distance queries
11 | Full-Text Search | High | FullTextContains, BM25 ranking

## Anatomy of a Rule

### Rule Structure

- Frontmatter — title, impact level, tags
- Why it matters — brief explanation
- Incorrect — anti-pattern with explanation
- Correct — best practice with explanation
- Language-specific — .NET, Java, Python examples

### Impact Levels

- Critical Prevents data loss or outages
- High Significant performance / cost impact
- Medium Recommended best practice
- Low Minor optimization

---
title: Use Literal Integers for TOP
impact: HIGH
tags: [query, parameterization]
---
❌ Incorrect — parameterized TOP
SELECT TOP @limit * FROM c
// 400 Bad Request at runtime
✅ Correct — literal integer
SELECT TOP 10 * FROM c
// Works. Validate as int in code
// before string interpolation.
The Feedback Loop

## Automated Testing Framework

Contract-first testing that measures and improves agent quality over time

## The Self-Improving Loop

1 • Issue
Create iteration
issue → assign
to Copilot
→
2 • Generate
Agent reads skills
+ API contract
→ writes app
→
3 • Test
CI starts emulator
runs pytest suite
posts results
→
4 • Evaluate
Agent classifies
failures → creates
new rules
→
5 • Improve
Merge rules →
next iteration
scores higher

Key insight: Tests are written against a fixed API contract, not against the generated code. The agent is told exactly which endpoints, field names, and status codes to implement — making testing deterministic regardless of what the agent produces.

## Test Scenarios

Real-world application patterns that exercise different Cosmos DB features

🎮 Gaming Leaderboard
Materialized views, ranking queries, synthetic partition keys, ETag concurrency, cascade deletes
🛒 E-Commerce Order API
Multi-entity containers, order lifecycle, transactional batch, change feed patterns
💬 AI Chat RAG
Vector search, embedding policies, hybrid queries, full-text search integration
📡 IoT Device Telemetry
Time-series ingestion, hierarchical partition keys, TTL, hot partition avoidance
🏢 Multi-Tenant SaaS
Tenant isolation, throughput allocation, cross-tenant queries, data partitioning

## Proven Results

### Score Improvement Over Iterations

7/10
Iter 1
.NET
7/10
Iter 2
Java
9/10
Iter 3
Python
81%
Batch
5 runs

### What Improved

- COUNT-based ranking applied from start after rule added
- ETag concurrency with correct SDK-specific APIs
- Composite index directions now match queries
- Python async deps automatically included
- Cascade deletes documented and followed

### Feedback Loop Validated

- Rules from iteration 1 applied correctly in iteration 3
- Found and fixed a bug in the skill's own examples
- Each iteration surfaces new gaps → new rules

## Skill Architecture

### File Structure

skills/cosmosdb-best-practices/
├── SKILL.md # Entry point (triggers activation)
├── AGENTS.md # Compiled rules (monolithic)
├── metadata.json # Version & metadata
├── README.md # Documentation
└── rules/
├── _sections.md # Category definitions
├── _template.md # New rule template
├── model-*.md # Data modeling
├── partition-*.md # Partition keys
├── query-*.md # Query optimization
├── sdk-*.md # SDK best practices
├── vector-*.md # Vector search
└── fts-*.md # Full-text search

### Progressive Disclosure

- Only skill name + description loaded at startup
- SKILL.md loads when agent detects relevance
- Individual rules/ read on demand
- Minimizes token/context usage

### Build Pipeline

# Compile individual rules → AGENTS.md
npm run build
# Validate rule files
npm run validate

## Works With Your Agent

One install, every major AI coding agent

🤖
GitHub Copilot
🧠
Claude Code
💎
Gemini CLI
📝
OpenCode
🏭
Factory
🔮
OpenAI Codex
🌐
GitHub.com
# Install with one command
npx skills add AzureCosmosDB/cosmosdb-agent-kit

## Get Started

### For Developers

- Install: `npx skills add AzureCosmosDB/cosmosdb-agent-kit`
- Use naturally: Ask your agent about Cosmos DB tasks
- Rules activate automatically when relevant context is detected
- Works with .NET, Java, Python, Node.js

### For Contributors

- Add new rules using the template in `rules/_template.md`
- Run `npm run build` to recompile
- Run test scenarios to validate improvements
- Submit PRs to strengthen the knowledge base

### For Teams

- Fork the repo to run the batch testing pipeline
- Create custom scenarios matching your workloads
- Measure agent quality with contract-first tests
- Generate improvement recommendations automatically

### Links

- 📦 GitHub Repository
- 📖 Agent Skills Standard
- 📚 Cosmos DB Documentation

Open Source • MIT License

# Ship Better
Cosmos DB Code

75+ rules. 11 categories. One install.
Every AI agent becomes a Cosmos DB expert.

npx skills add AzureCosmosDB/cosmosdb-agent-kit

github.com/AzureCosmosDB/cosmosdb-agent-kit