{
  "markdown": "# cosmosdb-agent-kit\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n[![Good First Issues](https://img.shields.io/github/issues/AzureCosmosDB/cosmosdb-agent-kit/good-first-issue?color=7057ff&label=good%20first%20issues)](https://github.com/AzureCosmosDB/cosmosdb-agent-kit/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22)\n[![Discussions](https://img.shields.io/github/discussions/AzureCosmosDB/cosmosdb-agent-kit)](https://github.com/AzureCosmosDB/cosmosdb-agent-kit/discussions)\n\nA collection of skills for AI coding agents working with Azure Cosmos DB. Skills are packaged instructions and scripts that extend agent capabilities.\n\n![agent-kit-cosmosdb (1)](https://github.com/user-attachments/assets/0a2c2e5f-62ee-4741-adda-9af790980761)\n\nSkills follow the [Agent Skills](https://agentskills.io/) format and the kit ships with plugin manifests for **Claude Code**, **Codex**, **Cursor**, **Gemini CLI**, **Grok Build**, **Kimi Code**, and **GitHub Copilot**.\n\n## Where this works best\n\nThis 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:\n\n- **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**).\n- **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.\n\n**If you are in a constrained setup** (always-on injection plus a smaller-context model), prefer one of the following:\n\n- Load a **single, focused skill** for the task at hand instead of the full set, or\n- Switch to a **larger-context model**, or\n- Use a host that supports **on-demand skill discovery**.\n\n> These recommendations are based on internal skill-efficacy testing across multiple models and delivery mechanisms. Exact context limits vary by model and host.\n\n## Recommended models\n\nWe evaluate agent builds on Azure Cosmos DB with an **execution-graded** benchmark on Microsoft Bench: a realistic *AI Chat with RAG* task (Python / FastAPI) built against a **live** Azure Cosmos DB account (Entra ID, no keys) and scored by hidden integration tests. `reward` is the fraction of checks passed, averaged over roughly **100 independent attempts per model**. Based on this, for building non-trivial Cosmos DB applications we recommend:\n\n| Tier | Models (as tested) | Avg reward | Guidance |\n|------|--------------------|-----------|----------|\n| **Recommended** | GPT-5.4, Claude Opus 4.8 | 0.79 – 0.82 | Strongest Cosmos DB build quality; the best default choice. |\n| **Capable** | Claude Sonnet 4.5, Claude Opus 4.5, GPT-5.2, Claude Sonnet 4.6 | 0.59 – 0.68 | Solid results; pair with the kit and a clear specification. |\n| **Best for simpler tasks** | Claude Haiku 4.5, GPT-4.1 | 0.11 – 0.15 | Fine for individual operations; struggle with full application builds regardless of how skills are delivered. |\n\n**How to read this:** the ranking reflects intrinsic model capability on Cosmos DB build tasks, measured *without* any skill injected. Model capability is the dominant factor in outcome quality — **choose a Recommended-tier model first**, then apply the kit.\n\n### Delivery mechanism matters as much as the model\n\nThe same testing measured *how* the skill is delivered, and this is where the results are strongest:\n\n- **Always-on injection can hurt — including the strongest models.** Injecting the **entire** skill set as always-on context (~500&nbsp;KB) **overflowed the context window and scored 0** on every model whose usable prompt budget is roughly **130K tokens or less**. And a multi-file always-on variant **significantly reduced quality on large-context, capable models too** (for example Claude Opus 4.8 and GPT-5.2 both dropped by roughly **0.3**). In other words, forcing the full skill payload into every prompt is counter-productive.\n- **Progressive / on-demand delivery is the safe mode.** It avoided both failure modes — no overflow, no regression on strong models — and **matched no-skill quality**. It also costs **roughly 5–13× fewer input tokens than always-on injection** (progressive sends about as many tokens as a no-skill run, because it loads a skill only when needed; always-on re-sends the full payload on every call).\n\nSo the combined recommendation is simple: **use a Recommended-tier model *and* deliver skills on demand.** This is exactly what the kit is designed for (see [Where this works best](#where-this-works-best)).\n\n> On this well-specified build task, progressive delivery *matches* a no-skill baseline rather than beating it — the strong models already know a lot. The measurable win today is avoiding the harm of always-on injection at a fraction of the token cost; benefits on *under-specified* prompts and additional scenarios are still being measured.\n\n### Scope & caveats\n\n- Results come from a single build scenario (AI Chat + RAG), a single language (Python), and a single agent host, graded by hidden integration tests over ~100 attempts per model per configuration.\n- These tiers are **directional and specific to this evaluation** (one scenario, one language, one host). Model names reflect the versions exposed by the evaluation harness at test time (mid-2026); exact scores will shift as models evolve and may not transfer to other tasks.\n- On this well-specified task, Recommended-tier models already score well **without** the skill; the kit's role is to encode Cosmos DB-specific best practices and steer agents away from common anti-patterns. Testing is being extended to under-specified prompts and additional scenarios.\n\n## Available Skills\n\n| Skill | Description | Status |\n|-------|-------------|--------|\n| [cosmosdb-best-practices](skills/cosmosdb-best-practices/) | Performance optimization (111 rules, 12 categories) | ✅ Stable |\n| migration-capacity-planning | RU calculation, data sizing, pre-split partitions | 🚧 Planned |\n\n### cosmosdb-best-practices\n\nAzure Cosmos DB performance optimization guidelines containing 111 rules across 12 categories, prioritized by impact.\n\n**Use when:**\n- Writing new code that interacts with Cosmos DB\n- Designing data models or choosing partition keys\n- Reviewing code for performance issues\n- Optimizing queries or throughput configuration\n\n**Categories covered:**\n- Data Modeling (Critical)\n- Partition Key Design (Critical)\n- Query Optimization (High)\n- SDK Best Practices (High)\n- Design Patterns (High)\n- Vector Search (High)\n- Full-Text Search (High)\n- Security (High)\n- Indexing Strategies (Medium-High)\n- Throughput & Scaling (Medium)\n- Global Distribution (Medium)\n- Developer Tooling (Medium)\n- Monitoring & Diagnostics (Low-Medium)\n\n## Installation\n\n### APM (recommended — all harnesses at once)\n\n```bash\napm install AzureCosmosDB/cosmosdb-agent-kit\n```\n\nInstalls the skill across GitHub Copilot, Claude Code, Cursor, Codex, Gemini, and Kimi Code in one command.\n\n### Universal one-liner (all agents)\n\n```bash\nnpx skills add AzureCosmosDB/cosmosdb-agent-kit\n```\n\nThis drops the skill catalog into whichever agent you're using.\n\n### GitHub Copilot CLI\n\n```\n/plugin marketplace add AzureCosmosDB/cosmosdb-agent-kit\n/plugin install cosmosdb@cosmosdb-agent-kit\n```\n\n### Claude Code\n\n```\n/plugin install cosmosdb@claude-plugins-official\n```\n\n### Gemini CLI\n\n```bash\ngemini extensions install https://github.com/AzureCosmosDB/cosmosdb-agent-kit\n```\n\n### Grok Build\n\nAdd the Agent Kit marketplace, install the plugin, then verify that Grok discovered its skills:\n\n```bash\ngrok plugin marketplace add AzureCosmosDB/cosmosdb-agent-kit\ngrok plugin install cosmosdb --trust\ngrok inspect\n```\n\nThe marketplace catalog lives at `.grok-plugin/marketplace.json`, and the plugin uses the root\n`plugin.json` manifest. Only install trusted plugin sources; Grok requires `--trust` before\nactivating a remote plugin's skills and MCP servers.\n\n### Kimi Code CLI\n\nInstall directly from GitHub (recommended):\n\n```\n/plugins install https://github.com/AzureCosmosDB/cosmosdb-agent-kit\n/reload\n```\n\nOr add the custom marketplace catalog, then install from the plugin manager (`/plugins`):\n\n```\n/plugins marketplace https://raw.githubusercontent.com/AzureCosmosDB/cosmosdb-agent-kit/main/kimi-marketplace.json\n```\n\nThe plugin manifest lives at `.kimi-plugin/plugin.json` and the catalog at `kimi-marketplace.json`.\n\n### OpenAI Codex CLI\n\nAdd the repo marketplace, then install from the Plugins Directory in the ChatGPT desktop app:\n\n```\ncodex plugin marketplace add AzureCosmosDB/cosmosdb-agent-kit\n```\n\nThe plugin manifest lives at `.codex-plugin/plugin.json` and the marketplace catalog at `.agents/plugins/marketplace.json` (Codex also reads the legacy `.claude-plugin/marketplace.json`).\n\n### Per-agent plugin directories\n\nThe repository includes ready-made plugin manifests:\n\n| Agent | Manifest |\n|-------|----------|\n| Claude Code | `.claude-plugin/plugin.json` + `.claude-plugin/marketplace.json` |\n| OpenAI Codex | `.codex-plugin/plugin.json` + `.agents/plugins/marketplace.json` |\n| Cursor | `.cursor-plugin/plugin.json` |\n| Gemini CLI | `gemini-extension.json` + `GEMINI.md` |\n| Grok Build | `.grok-plugin/marketplace.json` + `plugin.json` |\n| Kimi Code | `.kimi-plugin/plugin.json` |\n| GitHub Copilot | `skills/cosmosdb-best-practices/SKILL.md` (auto-detected) |\n\n## Website\n\nA project website is available in `docs/` and is designed for GitHub Pages publishing.\n\n- Main page: `docs/index.html`\n- Styles: `docs/styles.css`\n- Interactions + survey flow: `docs/app.js`\n\nThe website includes a feedback survey that opens a prefilled GitHub issue so users can share improvements for Agent Kit without requiring a backend service.\n\n### Preview locally\n\n```bash\n# Option 1: VS Code Live Server\n# open docs/index.html with Live Server\n\n# Option 2: Python static server\npython -m http.server 8080 --directory docs\n```\n\nThen open `http://localhost:8080`.\n\n### Publish with GitHub Pages\n\nIn repository settings, set Pages source to `Deploy from a branch`, branch `main`, folder `/docs`.\n\n## Usage\n\nSkills are automatically available once installed. The agent will use them when relevant tasks are detected.\n\n**Examples:**\n```\nReview my Cosmos DB data model\n```\n```\nHelp me choose a partition key for my orders collection\n```\n```\nOptimize this Cosmos DB query\n```\n\n## Skill Structure\n\nEach skill contains:\n- `SKILL.md` - Instructions and index for the agent (what agents read; links to rules)\n- `rules/` - Individual rule files\n- `metadata.json` - Version and metadata\n\n## Compatibility\n\nWorks with Claude Code, Codex, Cursor, Gemini CLI, Grok Build, Kimi Code, GitHub Copilot, and other Agent Skills-compatible tools.\n\n## Contributing\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for contribution guidelines.\n\n## Evaluation (Local Only)\n\nThis project includes a [Vally](https://github.com/microsoft/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:\n\n```bash\n# Install Vally by following the instructions at https://github.com/microsoft/vally\n\n# Run evaluations\nvally run evals/cosmosdb-best-practices/eval.yaml -v\n\n# Check skill readiness\nvally check skills/cosmosdb-best-practices\n```\n\n**Looking for a way to help?** Check out our [good first issues](https://github.com/AzureCosmosDB/cosmosdb-agent-kit/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) or browse the [Discussions](https://github.com/AzureCosmosDB/cosmosdb-agent-kit/discussions) board to share ideas.\n\n## Contributors\n\nThanks to everyone who has contributed rules, fixes, and ideas!\n\n<!-- ALL-CONTRIBUTORS-LIST:START -->\n<!-- prettier-ignore-start -->\n<!-- markdownlint-disable -->\n<!-- markdownlint-restore -->\n<!-- prettier-ignore-end -->\n<!-- ALL-CONTRIBUTORS-LIST:END -->\n\nContributions of any kind welcome! See the [contributing guide](CONTRIBUTING.md) to get started.\n\n## Evaluation with Vally\n\nThis project uses [Vally](https://github.com/microsoft/vally) to evaluate skill quality, testing that the agent produces correct Cosmos DB guidance across data modeling, partitioning, queries, SDK usage, and throughput scenarios.\n\n```bash\n# Install Vally by following the instructions at https://github.com/microsoft/vally\n\n# Run evaluations (mock executor, no API key needed)\nvally run evals/cosmosdb-best-practices/eval.yaml -v\n\n# Check skill readiness\nvally check skills/cosmosdb-best-practices\n\n# Run with a real model (requires Copilot auth)\nvally run evals/cosmosdb-best-practices/eval.yaml --executor copilot-sdk --model claude-sonnet-4.6\n```\n\n## Changelog\n\nSee [CHANGELOG.md](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.\n\nWhen you merge a PR, add a new dated entry at the top of `CHANGELOG.md`.\n\n## License\n\nMIT\n",
  "bytes": 13445,
  "sha": "a2b96628b3ac7bba0ef3c5a67de2b7b5e58fffaa70941ba101f600ed4f3a526d",
  "repo_slug": "azurecosmosdb/cosmosdb-agent-kit",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/plg_azurecosmosdb_cosmosdb_agent_kit_a898c349/readme"
}