Azure Cosmos DB TypeScript Skill
Gives TypeScript and JavaScript coding agents practical Cosmos DB data-access patterns.
The skill recommends Microsoft Entra authentication, distinguishes data and management planes, and places keys in environment variables, reducing obvious credential exposure. However, CRUD, bulk deletion, and container-creation examples provide no user confirmation, least-privilege guidance, data-flow disclosure, or rollback plan; the connection-string example also lacks sensitive-data warnings, so points were deducted.
The document covers authentication, CRUD, queries, partition keys, error handling, and concurrency with useful status-code guidance. However, the main file uses executeBulkOperations while the reference uses bulk, and static evidence cannot establish API/version consistency. No skill-specific executable tests are shown, so the score remains conservative under the static cap.
Triggers, the TypeScript/JavaScript audience, and the data-plane versus management-plane boundary are reasonably clear, with broad common Cosmos DB coverage. Non-fit cases, input/output constraints, permission prerequisites, environment limitations, and Chinese-language guidance are under-specified, so points were deducted.
The skill has YAML metadata, installation and environment sections, progressive topical organization, references, best practices, related SDKs, an MIT license, and version fields. It lacks a changelog, explicit maintenance ownership and update path, FAQ, known-limitations section, and dependency version-lock guidance, so points were deducted.
The examples provide a useful starting point for CRUD, queries, pagination, bulk processing, and ETag concurrency, and parameterized queries and error handling add practical value. However, the conflicting bulk APIs and undefined context such as generateItems prevent treating the output as directly compilable or fully production-ready, so points were deducted.
The repository materials show general CI, evaluation workflows, and harness tests, providing some auditability. The supplied evidence does not show skill-specific tests, acceptance criteria, or third-party execution results; key SDK claims remain primarily self-documented, warranting only limited static evidence credit.
- The bulk reference uses container.items.bulk while the main document uses executeBulkOperations; verify against the pinned SDK types and official API documentation before use.
- Deletes, bulk writes, container creation, and cross-partition queries can cause irreversible data changes or material cost; confirmation, authorization, cost preview, and recovery procedures are not specified.
- The skill does not systematically explain the sensitivity of Cosmos endpoints, document contents, query results, or telemetry, nor logging-redaction requirements.
- No skill-specific acceptance tests or compilation evidence are supplied; treat the snippets as unverified starting points rather than production-validated code.
What does this skill do, and when should you use it?
This skill targets Azure Cosmos DB NoSQL data-plane work through the @azure/cosmos SDK. It covers document creation, reads, replacements, upserts, deletes, patches, parameterized queries, pagination, cross-partition queries, and bulk operations. It also documents Microsoft Entra authentication, key-based authentication, partition keys, ETag concurrency, and error handling. It does not provision or manage Cosmos DB accounts, databases, or containers through ARM.
Guides agents through installing @azure/cosmos and @azure/identity, configuring endpoint, database, container, and authentication variables, and creating CosmosClient, database, and container objects. It produces examples for document CRUD, Patch, SQL queries, pagination, cross-partition queries, bulk operations, simple and hierarchical partition keys, ETag-based conditional updates, handling 404/409/412/429 errors, and disposing the client during shutdown.
- A Node.js and TypeScript backend developer needs a Cosmos DB document service layer.
- An application team needs parameterized NoSQL queries with paginated reads.
- A service needs to create, read, replace, delete, or patch many documents in bulk.
- A Cosmos DB application needs Microsoft Entra, key-based, or connection-string authentication examples.
- A multi-tenant application needs simple or hierarchical partition-key patterns and guidance for avoiding unnecessary cross-partition queries.
What are this skill's strengths and limitations?
- Covers the practical data-plane flow from client setup through CRUD, queries, bulk work, and concurrency control.
- Includes Microsoft Entra, key-based, and connection-string authentication examples.
- Addresses parameterized queries, partition keys, 429 responses, and ETag handling.
- Clearly separates the data-plane SDK from the ARM management SDK.
- It is limited to JavaScript/TypeScript @azure/cosmos data-plane operations and does not cover ARM resource management.
- It requires Node.js 20 or later and an Azure Cosmos DB environment.
- The source does not provide independent test coverage or verification results for this individual skill.
- Users must supply the Cosmos endpoint, database, container, and authentication configuration.
How do you install this skill?
In Copilot CLI or a compatible skills installation flow, run: npx skills add microsoft/skills, then select azure-cosmos-ts in the wizard. The collection is installed into the chosen agent directory, such as .github/skills/ for GitHub Copilot. You may also copy the .github/plugins/azure-sdk-typescript/skills/azure-cosmos-ts/ directory from the repository; the source does not specify another standalone installer.
How do you use this skill?
Give the coding agent a request such as: “Use @azure/cosmos and TypeScript to build a Cosmos DB document service with parameterized queries, partition keys, and 429 retry handling.” Before use, configure COSMOS_ENDPOINT, COSMOS_DATABASE, and COSMOS_CONTAINER. For key authentication, configure COSMOS_KEY; for DefaultAzureCredential, configure AZURE_TOKEN_CREDENTIALS as described. The source does not provide a standalone execution or test command for this skill.
How does this skill compare with similar options?
Unlike @azure/arm-cosmosdb, this skill uses @azure/cosmos for data-plane work such as documents, queries, and stored procedures; @azure/arm-cosmosdb manages accounts, databases, and containers through ARM. @azure/identity supplies authentication credentials rather than performing Cosmos DB data operations.