SDK Workflow

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.

Before you push (required for every change)

Every code change must pass the checks that CI defines for the affected package

locally before you push or open a PR. This includes every pnpm workspace

package, not just sdk/*, including common/tools/* and

eng/containers/turborepo-remote-cache. Tools elsewhere under eng/* are not

workspace packages and use package-specific managers and scripts, so follow

their CI configuration.

For a pnpm workspace package, from its directory:

• pnpm format — auto-format with Prettier (this is what fixes a

check-format CI failure).

• pnpm check-format — verify formatting is clean (what CI runs).
• pnpm lint — check lint (pnpm lint:fix to auto-fix where possible).
• Build from the repository root: pnpm turbo build --filter=<package-name>... --token 1.
• Unit tests: run the package's test script; for sdk/*,

npx dev-tool check --tag=local runs build and unit tests.

For sdk/* packages, npx dev-tool check --fix bundles format + lint +

package.json validation in one step.

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 pnpm or node are not available, download and install

them before running any commands. Provisioning test resources requires PowerShell 7+

(pwsh) and the Azure PowerShell module. If pwsh is not installed, install it

from https://learn.microsoft.com/powershell/scripting/install/installing-powershell,

then run Install-Module -Name Az -Force -AllowClobber to install the Az module.

Always run pnpm install before building or running any dev-tool commands.

• Azure DevOps npm feed (devfeed priming): If pnpm install fails 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 running

npx artifacts-npm-credprovider at 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. See CONTRIBUTING.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 ...).

Running npm run build in a package directory will fail if dependencies aren't built.

• Dev-tool: Most package.json scripts delegate to dev-tool under the hood.

Use npx dev-tool <command> --help for detailed options. Dev-tool does not need

to be built — it runs via tsx after pnpm install.

• Checks: npx dev-tool check runs format, lint, build, test, and package.json

validation. Use --fix to auto-repair, --tag to select check categories.

• Versioning: When there is a new change to src/ after a release, the package

version must be incremented. Use npx dev-tool package increment-version to bump

the version in package.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:

  node eng/tools/ci-runner/index.js check-package-version <service-dir> -packages "<artifact-name>"

where <service-dir> is the first path segment after sdk/ (e.g. keyvault for

sdk/keyvault/keyvault-keys) and <artifact-name> is the package name with @

removed and / replaced by - (e.g. azure-keyvault-keys for

@azure/keyvault-keys). If the check exits with a non-zero code, run

npx dev-tool package increment-version from 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-AzAccount or az login). Never use device

code authentication.

• Test resources: When provisioning test resources with New-TestResources.ps1,

use the TME tenant and its subscription Azure 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 -SubscriptionId explicitly.

After provisioning, write the output environment variables to a .env file in every

library under the service folder. For example, for sdk/keyvault, write the .env

file in sdk/keyvault/keyvault-keys, sdk/keyvault/keyvault-certificates, etc.

• Test proxy: npx dev-tool run test:vitest automatically 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.md for details on each agent — archie

(API design), scribe (documentation), sentinel (security), tester

(test coverage), dash (performance), dexter (dependencies),

mgmt-review (management SDKs).