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

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

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

Azure Cosmos DBAgent Kit