Azure Cosmos DB Java Skill
Guides Java developers in building globally distributed, partitioned, and reactive Azure Cosmos DB applications.
The material uses environment variables for the Cosmos key and demonstrates database, container, and item deletion, but lacks least-privilege guidance, user confirmation, data-flow disclosure, redaction, rollback, and deletion-recovery instructions. No malicious or covert exfiltration behavior is shown, so a moderate score is retained while deducting for incomplete security governance.
SKILL.md and examples.md cover sync, async, CRUD, queries, and error handling, but show several questionable paths: the synchronous createDatabaseIfNotExists result is chained with map, variables are redeclared in the same scope, an async delete chain depends on an item from a delete response, and no skill-specific executable tests are provided. Static evidence is insufficient for a score above 10.
The name, Java SDK target, Cosmos DB scenarios, and trigger phrases are clear, covering sync, async, partitioning, queries, and consistency. However, non-fit ranges, input/output boundaries, compatibility versions, semantic false-trigger controls, Chinese-language support, and mainland-China network reachability are not documented, so points are deducted.
The skill has front matter, MIT licensing, version 1.0.0, installation notes, layered reference examples, best practices, error handling, and official reference links. It nevertheless uses LATEST, placeholder versions, and placeholder credentials, with no changelog, explicit maintenance owner, update path, or known-limitations section, so it does not receive full marks.
The material can accelerate generation of Cosmos Java client, CRUD, and query code and mentions RU cost and retry behavior. However, examples contain possible compile/runtime correctness issues, and destructive operations lack confirmation and rollback guidance; substantial review and correction may still be required, so the static score is kept below 7.
Maven, API, product, sample, performance, and troubleshooting links provide some traceability. They are reference links rather than skill-specific validation records, and no committed tests or third-party execution evidence covering this skill's key paths is shown, so the static score remains within the capped range.
- Do not use LATEST directly; pin a verified azure-cosmos version or Azure SDK BOM version.
- Prefer or supplement key authentication with a least-privilege DefaultAzureCredential approach, and never expose keys in logs or examples.
- The database, container, and item deletion examples are destructive; add explicit confirmation, backup, and recovery procedures before production use.
- Compile and validate the synchronous map chain, duplicate variable declarations, and async delete-response access before adopting the examples.
- Mainland-China reachability and Chinese-language support are undocumented; evaluate the network environment separately when relying on Azure services and online documentation.
What does this skill do, and when should you use it?
This skill provides development guidance for the Azure Cosmos DB NoSQL API through the Java SDK. It covers Maven setup, key-based authentication, synchronous and asynchronous clients, database and container management, CRUD, queries, partition keys, consistency levels, and request units. It also includes connection configuration, error handling, and production-oriented practices for Java applications using Cosmos DB.
Shows developers how to add the azure-cosmos Maven dependency, read COSMOS_ENDPOINT and COSMOS_KEY environment variables, create CosmosClient or CosmosAsyncClient, manage databases and containers, perform create/read/update/delete and query operations, and handle CosmosException cases such as conflicts and rate limiting.
- A Java backend developer adding the Azure Cosmos DB NoSQL API to a new application can use it for Maven setup and client initialization.
- A team building high-throughput or reactive services can follow the CosmosAsyncClient and chained asynchronous examples.
- A developer designing a Cosmos DB data model can use the partition-key guidance on cardinality, distribution, and query patterns.
- A globally distributed application team can use the preferred-region, consistency-level, and direct-mode configuration examples.
- A developer troubleshooting database operations can use the status-code, request-charge, and retry-after handling patterns.
What are this skill's strengths and limitations?
- Covers both synchronous and asynchronous clients, including reactive chaining.
- Provides an end-to-end baseline from dependency setup through databases, containers, CRUD, and queries.
- Includes practical guidance on partition keys, consistency, request units, preferred regions, direct mode, and throttling.
- Offers reusable Java and Maven examples.
- The authentication examples only demonstrate account-key authentication.
- The dependency example uses `LATEST` rather than a pinned SDK version.
- No test coverage or compatibility matrix is provided for this individual skill.
- An Azure Cosmos DB account, endpoint, and primary key are required by the examples.
How do you install this skill?
Add the com.azure:azure-cosmos dependency to the project Maven configuration, or manage its version through the Azure SDK BOM. Set COSMOS_ENDPOINT and COSMOS_KEY environment variables. The full skill collection can be installed with npx skills add microsoft/skills; the README does not document a separate installation command for this individual skill directory.
How do you use this skill?
In an Agent Skills-compatible coding agent, provide a request such as “Use CosmosClient Java to create a Cosmos DB database and container” or “Implement Cosmos DB Java CRUD with CosmosAsyncClient.” The agent can follow the skill’s Java, Maven, authentication, partitioning, querying, and error-handling patterns.