Azure Cosmos DB Python Service Builder
Build secure, testable Azure Cosmos DB NoSQL services for Python and FastAPI applications.
The evidence favors DefaultAzureCredential, avoids production keys, limits emulator keys to local use, and requires parameterized queries. However, delete operations lack user confirmation, rollback, or recovery guidance; partition-key authorization is stated as a principle but not implemented; client-lifecycle examples are inconsistent; and error logging may expose endpoint and internal details, so points are deducted.
The material supplies client, service-layer, error-handling, retry, and testing templates with an understandable happy path. Static evidence also shows inconsistencies between synchronous Cosmos clients, threadpool wrapping, and async context-manager guidance, many TODO placeholders, unpinned dependencies, and silent None/empty-list/False failure conventions. No execution results are provided, so the static ceiling and deductions apply.
The intended audience, Cosmos DB Python/FastAPI scenarios, and major triggers are fairly clear, covering authentication, CRUD, partitioning, and tests. However, triggers such as NoSQL database and add persistence are broad, the templates assume a specific FastAPI project structure and models, and non-fit boundaries, Chinese support, and mainland-China network reachability are not documented, so points are deducted.
The evidence includes installation, environment variables, layered references, templates, MIT licensing, author metadata, and version 1.0.0, providing a reasonably usable information architecture. It lacks a compatibility matrix, dependency pinning, changelog, explicit maintenance owner, and update path; the repository README also describes the project as work in progress, so points are deducted.
The templates theoretically cover client setup, CRUD, queries, partitioning, error handling, and tests, so they can support the core implementation task. However, substantial renaming, model work, and project configuration are required; production-grade quality and representative outputs are not statically verified; and some examples require correction. The static effectiveness ceiling therefore limits the score.
The evidence is versioned and auditable and includes test templates, integration-test patterns, and repository CI indicators. It does not provide executed results, a complete key-path test suite, or independent corroboration for this skill. Repository badges alone do not verify coverage of this skill, so only limited credit is warranted.
- Do not treat the templates as production-ready without reconciling the sync/async client strategy and adding explicit client and credential shutdown.
- Add authorization, user confirmation, auditing, and failure-recovery controls before deletes, cross-partition moves, or cross-tenant access.
- Constrain extra_filter callers and review exception logging and configuration loading to reduce query-fragment injection and sensitive-data exposure.
- The material does not establish Azure service reachability in mainland-China network or regional environments; verify this separately before deployment.
What does this skill do, and when should you use it?
This skill is for developers implementing Azure Cosmos DB NoSQL services with Python and FastAPI. It covers client setup, DefaultAzureCredential and emulator authentication, service-layer CRUD, partition keys, parameterized queries, and test-driven development. It also defines Pydantic model tiers, graceful degradation, singleton container initialization, and client or credential lifecycle management. It fits Azure application teams seeking production-oriented implementation patterns, but it does not provision Cosmos DB infrastructure.
It guides coding agents through installing azure-cosmos and azure-identity, reading Cosmos endpoint, database, container, and credential settings, creating clients with DefaultAzureCredential or emulator keys, structuring FastAPI routers and Cosmos service classes, implementing CRUD and document-model conversion, validating partition-key access, writing parameterized queries, and creating pytest tests with mocked containers.
- A Python backend developer adding Cosmos DB persistence to a FastAPI project or workspace.
- A team that needs emulator authentication locally and managed identity or another Entra credential in Azure production.
- An application developer designing partition-key isolation, authorized data access, and low-scan query patterns.
- A team that wants tests written before implementation and needs a mockable Cosmos container dependency.
- A backend project separating Cosmos documents, Pydantic API models, and business logic through a service layer.
What are this skill's strengths and limitations?
- Covers authentication, lifecycle management, service layers, models, partitioning, queries, and testing in one implementation guide.
- Clearly prioritizes DefaultAzureCredential and limits keys to emulator or local authentication scenarios.
- Includes concrete FastAPI, Pydantic, and pytest patterns.
- Emphasizes parameterized queries, authorization-aware partition validation, and graceful degradation.
- The repository is MIT-licensed and supports collection installation through npx skills add.
- Focuses on Cosmos DB NoSQL service implementation and does not cover resource provisioning or full infrastructure setup.
- It depends on Python, Azure SDK packages, FastAPI, Pydantic, and pytest, but the source does not specify supported versions.
- The source provides no independent test coverage or execution results for this specific skill.
- Developers must integrate asynchronous execution, singleton lifetime, and context-manager handling into their own application structure.
How do you install this skill?
Run npx skills add microsoft/skills in the target project and select azure-cosmos-db-py in the installation wizard. The README also documents copying a selected skill into an agent directory. The source file for this skill is .github/plugins/azure-sdk-python/skills/azure-cosmos-db-py/SKILL.md; the installer determines the target agent directory.
How do you use this skill?
In an Agent Skills-compatible coding agent, ask for something such as “Add Azure Cosmos DB NoSQL persistence to this FastAPI app using DefaultAzureCredential, partition keys, a service-layer CRUD design, and pytest tests.” Trigger phrases include “Cosmos DB,” “Python Cosmos SDK,” and “database service layer.” Configure COSMOS_ENDPOINT, COSMOS_DATABASE_NAME, and COSMOS_CONTAINER_ID; add COSMOS_KEY for emulator scenarios.