SDK Workflow
Developmentsdk-workflowSDK Workflow is an Agent Skill for development published in the Azure/azure-sdk-for-js repository on GitHub: a SKILL.md instruction file an AI agent can load to do this task.
**UTILITY SKILL** — Must be consulted for SDK development workflow tasks. Routes agents to the correct tools and documentation for building, testing, linting, formatting, provisioning, deploying, and other package development tasks. WHEN: "build package", "run tests", "lint code", "format code", "run checks", "prepare samples", "publish samples", "apply customization", "run migrations", "bump version", "extract API", "update snippets", "check API compatibility", "manage test recordings", "provision test resources", "deploy test resources", "create test resources", "set up test environment", "authenticate to Azure", "login to Azure", "release package", "increment version", "troubleshoot CI", "fix CI failure", "CredScan", "credential scan", "push recordings", "asset sync", "update recordings".
How to use this skill
Bring this guide into your coding agent with a prompt tailored to the tool you use.
- Open your project in Codex.
- Copy and paste the prompt below.
- Review files and risks before approving any action.
Inspect the Agent Skill at https://github.com/Azure/azure-sdk-for-js/blob/HEAD/.github/skills/sdk-workflow/SKILL.md and all supporting files. Report provenance, permissions, scripts, dependencies, and security risks. Propose an exact installation into .agents/skills/sdk-workflow, but wait for my approval before writing files or running scripts.
Copying this prompt does not install or run the skill. Review third-party files before use.
SDK Development Workflow
This skill routes you to the correct tools and documentation for common SDK development tasks. Read the referenced docs — don't guess at commands.
Key Documentation
| What you need | Where to look |
|---|---|
| Dev workflows (build, test, lint, install deps, clean) | CONTRIBUTING.md § "Development Workflows" |
| Dev-tool CLI commands (checks, samples, API extraction, etc.) | common/tools/dev-tool/README.md |
| Writing and running tests | documentation/Quickstart-on-how-to-write-tests.md |
| Test recordings (record, playback, push) | documentation/Quickstart-on-how-to-write-tests.md § "Recording" |
| Provisioning test resources | eng/common/TestResources/README.md |
| Linting rules and troubleshooting | documentation/linting.md |
| Code generation from TypeSpec | documentation/Generate-code-from-TypeSpec.md |
| Customization after code generation | documentation/modular-customization.md |
| Build system (dual emit with warp) | documentation/dual-emitting-using-warp.md |
| Dependency management | documentation/dependency-management.md |
| Min/max dependency version testing | eng/tools/dependency-testing/README.md |
| Post-generation steps (changelog, samples, release prep) | documentation/steps-after-generations.md |
| Bundling for browser | documentation/Bundling.md |
| Resolving pnpm-lock.yaml merge conflicts | documentation/resolve-pnpm-lock-merge-conflict.md |
| Writing and running perf tests | sdk/test-utils/perf/GettingStarted.md |
| TypeSpec client generator CLI | eng/common/tsp-client/README.md |
| Code review agents (archie, scribe, sentinel, tester, dash, dexter) | documentation/reviewer-agents.md |
| Troubleshooting CI failures | documentation/Troubleshoot-ci-failure.md |
| Asset sync workflow (test recordings) | sdk/test-utils/recorder/ASSET_SYNC_WORKFLOW.md |
| CredScan suppression process | documentation/credscan-process.md |
Important Notes
- Prerequisites: If
pnpmornodeare not available, download and install them before running any commands. Provisioning test resources requires PowerShell 7+ (pwsh) and the Azure PowerShell module. Ifpwshis not installed, install it from https://learn.microsoft.com/powershell/scripting/install/installing-powershell, then runInstall-Module -Name Az -Force -AllowClobberto install the Az module. Always runpnpm installbefore building or running any dev-tool commands. - Azure DevOps npm feed (devfeed priming): If
pnpm installfails due to feed authentication errors, or when adding new packages that are not yet cached for anonymous access, authenticate to the Azure Artifacts feed by runningnpx artifacts-npm-credproviderat the repo root. pnpm is configured to install from the internal Azure Artifacts feed (devfeed); anonymous read access works for packages already in the feed, but authenticated access may be required when installing new or updated packages. SeeCONTRIBUTING.md§ "Authenticating to the Azure DevOps npm feed" for details. - Building with turbo: To build a package and its dependencies, use
pnpm turbo build --filter=<package-name>... --token 1(note the trailing...). Runningnpm run buildin a package directory will fail if dependencies aren't built. - Dev-tool: Most package.json scripts delegate to
dev-toolunder the hood. Usenpx dev-tool <command> --helpfor detailed options. Dev-tool does not need to be built — it runs via tsx afterpnpm install. - Checks:
npx dev-tool checkruns format, lint, build, test, and package.json validation. Use--fixto auto-repair,--tagto select check categories. - Pre-push checks: All code changes must pass build, format, lint, and test
checks locally before pushing — CI will fail otherwise. Run
npx dev-tool checkfor format, lint, and package.json validation, thennpx dev-tool check --tag=localfor build and unit tests. - Versioning: When there is a new change to
src/after a release, the package version must be incremented. Usenpx dev-tool package increment-versionto bump the version inpackage.json, update tracked version constants, and add a new changelog entry. Before opening or updating a PR, verify whether a version bump is needed by running the following from the repo root:
wherenode eng/tools/ci-runner/index.js check-package-version <service-dir> -packages "<artifact-name>"<service-dir>is the first path segment aftersdk/(e.g.keyvaultforsdk/keyvault/keyvault-keys) and<artifact-name>is the package name with@removed and/replaced by-(e.g.azure-keyvault-keysfor@azure/keyvault-keys). If the check exits with a non-zero code, runnpx dev-tool package increment-versionfrom the package directory and commit the result before opening the PR or pushing updates to PRs. - Azure authentication: You must be logged in to Azure when running tests live,
recording, or provisioning test resources. Always authenticate using the interactive
browser-based login flow (e.g.
Connect-AzAccountoraz login). Never use device code authentication. - Test resources: When provisioning test resources with
New-TestResources.ps1, use the TME tenant and its subscriptionAzure SDK Test Resources - TME(4d042dc6-fe17-4698-a23f-ec6a8d1e98f4). The script auto-selects this subscription when it detects a TME tenant, but you can also pass-SubscriptionIdexplicitly. After provisioning, write the output environment variables to a.envfile in every library under the service folder. For example, forsdk/keyvault, write the.envfile insdk/keyvault/keyvault-keys,sdk/keyvault/keyvault-certificates, etc. - Test proxy:
npx dev-tool run test:vitestautomatically manages the test proxy lifecycle. You do not need to start it manually. - Code review agents: Available locally for reviewing changes before pushing.
See
documentation/reviewer-agents.mdfor details on each agent — archie (API design), scribe (documentation), sentinel (security), tester (test coverage), dash (performance), dexter (dependencies), mgmt-review (management SDKs).