AGENT SKILL

pre-commit-checks

Pre-commit validation checks for azure-sdk-for-net. Use this before committing or pushing changes to SDK packages. Runs dotnet format, exports public API listings, updates snippets, and regenerates code as needed.

适用职业开发工程师
License 许可
MIT
最近更新
2026-11-14
Stars
★ 6.1k
Forks
5.2k

01 前言 Front Matter

name
pre-commit-checks
description
Pre-commit validation checks for azure-sdk-for-net. Use this before committing or pushing changes to SDK packages. Runs dotnet format, exports public API listings, updates snippets, and regenerates code as needed.

03 SKILL.md 正文

Pre-Commit Validation Checks

Run these checks after making changes to SDK packages under sdk/ and before staging, committing, or pushing. These steps may produce additional file changes that must be included in the commit.

General rule: Steps 3–5 are conditional to save time, but if you are unsure whether a step is needed, always run it. It is better to run an unnecessary script than to miss a required regeneration.

1. Determine scope from changed files

  • Derive the changed file list from git status --porcelain (or by combining git diff --name-only HEAD with git ls-files -o --exclude-standard) so that untracked (new) files are included.
  • From the changed file list, extract all unique ServiceDirectories — the first path segment after sdk/ (e.g., sdk/storage/... → storage, sdk/ai/... → ai).
  • For each ServiceDirectory, identify all affected packages = distinct sdk/{ServiceDirectory}/{PackageName}/ paths.
  • For each affected package, identify:
    • All csproj files that had changes beneath them (src, tests, samples, perf, stress, or any other project type).
    • The src csproj specifically = sdk/{service}/{package}/src/{Package}.csproj — this is used for GenerateCode.
  • The remaining steps must be run for each affected project/ServiceDirectory. If changes span multiple ServiceDirectories or packages, run for each one.

2. Run dotnet format (for every changed csproj)

For every csproj that had files change beneath it — src, tests, samples, perf, stress, or any other project type — run:

dotnet format <path-to-changed.csproj>

Identify affected csproj files by looking at the full changed file list: include any project where either (a) there is a changed .cs file with that .csproj as its nearest parent, or (b) the .csproj itself changed, or files such as .props, .targets, or .md changed under that project. This fixes style/formatting issues and may modify .cs files.

3. Conditionally run dotnet build /t:GenerateCode (per src csproj)

Exclusion: Skip this step entirely for the provisioning service directory. Provisioning libraries use their own generator and are not generated via TypeSpec/AutoRest.

Trigger condition — for each affected package's src csproj: Run this if ANY of the following files are in the changed file list:

  • Any file matching sdk/{service}/{package}/src/Generated/**
  • sdk/{service}/{package}/tsp-location.yaml
  • sdk/{service}/{package}/src/autorest.md
  • Any .cs file under sdk/{service}/{package}/src/ where a CodeGen* attribute was added, removed, or modified (e.g., CodeGenType, CodeGenModel, CodeGenClient, CodeGenMember, CodeGenSuppress, CodeGenSerialization, CodeGenVisibility). These attributes in custom (non-generated) code influence the generated output.

Important: Do not manually edit files under src/Generated/. Changes to generated code should only come from running the GenerateCode target.

Command:

dotnet build sdk/{service}/{package}/src/{Package}.csproj /t:GenerateCode

This regenerates code from TypeSpec/AutoRest specs. It may modify files under src/Generated/.

4. Conditionally run Export-API.ps1 (per ServiceDirectory)

Trigger condition — per ServiceDirectory: Run this if ANY of the following are true for ANY affected package within this ServiceDirectory:

  • Step 3 above ran for any package in this ServiceDirectory (generated code may affect public API).
  • Changed .cs files under sdk/{service}/{package}/src/ for any package in this ServiceDirectory contain public API surface changes. To determine this, inspect the diffs for:
    • New, removed, or renamed public or protected types (class, interface, struct, enum, record).
    • New, removed, or changed signatures of public or protected members (methods, properties, constructors, events, fields).
    • Visibility changes (e.g., internal → public).
    • Changes to base classes or implemented interfaces on public types.
    • New .cs files under src/ that contain public types.

Skip Export-API if changes are limited to:

  • Method body implementations (no signature changes).
  • internal or private members only.
  • XML doc comments or code comments.
  • .csproj configuration changes.

Command:

eng\scripts\Export-API.ps1 {ServiceDirectory}

This regenerates API listing files under sdk/{service}/{package}/api/*.cs. Uses dotnet build /t:ExportApi internally.

Note: Export-API operates at the ServiceDirectory level (not per-csproj), so run it once per affected ServiceDirectory.

5. Conditionally run Update-Snippets.ps1 (per ServiceDirectory)

Trigger condition — for each affected ServiceDirectory: Run this if ANY of the following are true:

  • Changed *.md files under sdk/{service}/ contain snippet references (```C# Snippet: markers).
  • Changed .cs files contain snippet regions (#region Snippet:).

Command:

eng\scripts\Update-Snippets.ps1 {ServiceDirectory}

Note: Update-Snippets operates at the ServiceDirectory level (not per-csproj), so run it once per affected ServiceDirectory.

This runs snippet-generator to sync code snippets into markdown files. May modify *.md and *.cs files.

6. Verify and include all changes

  • After running all applicable steps for all affected projects and ServiceDirectories, check for new/modified files with git status.
  • All changes produced by these steps must be included in the commit.
  • Do NOT commit if any of the above steps failed.

Execution order

Run the following steps in this order, respecting their scope (per package vs per ServiceDirectory):

  1. dotnet format first — run on all changed csproj files (src, tests, etc.) for each affected package.
  2. GenerateCode second — per src csproj, regenerates from specs (may override format changes in Generated/) for each affected package.
  3. Export-API third — run once per affected ServiceDirectory, after all GenerateCode runs for packages in that ServiceDirectory are complete; captures the final public API surface after generation.
  4. Update-Snippets fourth — run once per affected ServiceDirectory, after Export-API; captures any snippet changes from all prior steps.

When multiple packages/ServiceDirectories are affected, run steps 1–2 for each affected package, then steps 3–4 once per affected ServiceDirectory. Step 6 (verify) runs once at the end.

04 同仓库更多 Skills

Azure
Azure/azure-sdk-for-net

update-chat-api

Use when: updating, exporting, refreshing, or validating the public API baseline for Azure.Messaging.WebPubSub.Chat after a public API change.

开发工程师后端与接口
★ 6.1k
Azure
Azure/azure-sdk-for-net

search-documents

E2E workflow skill for Azure.Search.Documents SDK (TypeSpec + heavy customization). Handles full release cycles and partial updates: SHA update; code generation; build; customization fixes; ServiceVersion sync; testing; API export; changelog; version; samples; formatting; release metadata. WHEN: create new package version for Azure.Search.Documents; regenerate Azure.Search.Documents; fix Azure.Search.Documents bug; release Azure.Search.Documents; update Azure.Search.Documents spec. Do not use for Azure.ResourceManager.Search or Azure.Provisioning.Search.

开发工程师测试与质量Skill与智能体开发
★ 6.1k
Azure
Azure/azure-sdk-for-net

search-documents-version-diff

Diff the current Azure.Search.Documents public API surface against a previous published version and detect preview-to-preview regressions where the SDK customization layer was not bubbled up after a TypeSpec change. Use whenever the user asks to compare Azure.Search.Documents betas, verify no Azure.Search.Documents preview features dropped, regression audit between Azure.Search.Documents versions, sanity-check a release branch for Azure.Search.Documents, or investigate a missing Azure.Search.Documents preview feature — even if they don't say the word "diff". Specifically catches dropped wrappers (QueryAnswer/QueryCaption/QueryRewrites style), lost SearchOptions aggregator redirectors, `@@access("internal")` flips, deleted-instead-of-gated `#if AZURE_SEARCH_PREVIEW` blocks, dropped `ServiceVersion` enum values, and convenience-to-protocol downgrades.

★ 6.1k
Azure
Azure/azure-sdk-for-net

search-documents-typespec-validation

TypeSpec validation skill for Azure.Search.Documents SDK. Performs a COMPLETE validation of ALL operations, ALL models, ALL enums, and ALL properties against the TypeSpec definition at any pinned commit. Works for any API version. Generates a full gap report: missing features, extra features, naming mismatches, and recommended fix location. WHEN: "validate Azure.Search.Documents SDK against TypeSpec", "detect Azure.Search.Documents typespec feature gaps", "what is missing from the Azure.Search.Documents SDK", "compare Azure.Search.Documents SDK to spec", "full spec coverage audit for Azure.Search.Documents". Do NOT use for version-to-version diff or regression detection — use search-documents-version-diff instead.

Skill与智能体开发
★ 6.1k
Azure
Azure/azure-sdk-for-net

test-skill_file

Roll dice using a random number generator.

★ 6.1k
Azure
Azure/azure-sdk-for-net

roll-dice

Roll dice using a random number generator. Use when asked to roll a die (d6, d20, etc.), roll dice, or generate a random dice roll.

★ 6.1k