dotnet · jeffhandley · Feb 8, 2026 · Feb 8, 2026 · Feb 8, 2026 · Feb 8, 2026
diff --git a/.github/skills/api-diff/SKILL.md b/.github/skills/api-diff/SKILL.md
@@ -0,0 +1,36 @@
+---
+name: api-diff
+description: Generate an API comparison report between two .NET versions using the RunApiDiff.ps1 script. Invoke when the user asks to run, create, or generate an API diff.
+disable-model-invocation: true
+---
+
+# API Diff Generation
+
+Map the user's request to parameters for `release-notes/RunApiDiff.ps1` and run it. See [release-notes/RunApiDiff.md](../../../release-notes/RunApiDiff.md) for the full parameter reference.
+
+When no versions are mentioned, run with no parameters — the script auto-infers versions.
+
+## Mapping natural language to parameters
+
+| User says | Parameters |
+|---|---|
+| "generate the next API diff" | *(none)* |
+| ".NET 10 GA vs .NET 11 Preview 1" | `-PreviousMajorMinor 10.0 -CurrentMajorMinor 11.0 -CurrentPrereleaseLabel preview.1` |
+| "net9.0-preview6 to net10.0-preview5" | `-PreviousMajorMinor 9.0 -PreviousPrereleaseLabel preview.6 -CurrentMajorMinor 10.0 -CurrentPrereleaseLabel preview.5` |
+| ".NET 10 RC 2 vs .NET 10 GA" | `-PreviousMajorMinor 10.0 -PreviousPrereleaseLabel rc.2 -CurrentMajorMinor 10.0` |
+| "10.0.0-preview.7.25380.108 to 10.0.0-rc.1.25451.107" | `-PreviousVersion "10.0.0-preview.7.25380.108" -CurrentVersion "10.0.0-rc.1.25451.107"` |
+
+- **GA** or no qualifier → omit the PrereleaseLabel parameter
+- **Preview N** / **previewN** → `-PrereleaseLabel preview.N`
+- **RC N** / **rcN** → `-PrereleaseLabel rc.N`
+- **netX.Y-previewN** (TFM format) → `-MajorMinor X.Y -PrereleaseLabel preview.N`
+- Full NuGet version strings → use `-PreviousVersion` / `-CurrentVersion` directly
+- The "previous" version is always the older version; "current" is the newer one
+
+## Running the script
+
+```powershell
+.\release-notes\RunApiDiff.ps1 [mapped parameters]
+```
+
+Set an initial wait of at least 300 seconds — the script takes several minutes. Use `read_powershell` to poll for completion. The script does not print a final "done" message; it exits after generating a README.md in the output folder. After completion, summarize the results: how many diff files were generated and where.
@@ -1,27 +1,87 @@
 # RunApiDiff Script
 
-The [`RunApiDiff.ps1`](./RunApiDiff.ps1) script can automatically generate an API comparison report for two specified .NET previews, in the format expected for publishing in the dotnet/core repo.
+The [`RunApiDiff.ps1`](./RunApiDiff.ps1) script automatically generates an API comparison report between two .NET versions, in the format expected for publishing in the dotnet/core repo.
 
-## Instructions
+## Prerequisites
+
+- PowerShell 7.0 or later
+- The [Microsoft.DotNet.ApiDiff.Tool](https://www.nuget.org/packages/Microsoft.DotNet.ApiDiff.Tool). Install from the transport feed matching the version you're comparing, or use `-InstallApiDiff $true` to have the script install it automatically:
 
-1. Clone the dotnet/core repo. Let's assume you clone it into `D:\core`.
-2. Create a temporary directory. Let's assume you create it in `D:\tmp`.
-3. Install or update your copy of the APIDiff tool (use the latest transport feed):
 ```
-dotnet tool install --global Microsoft.DotNet.ApiDiff.Tool --source https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet10-transport/nuget/v3/index.json --prerelease
+dotnet tool install --global Microsoft.DotNet.ApiDiff.Tool --prerelease
 ```
-4. Run the command. Execution example:
+
+## Quick Start
+
+When run with no arguments, the script infers the next version to diff by scanning existing `api-diff` folders in the repository. For example, if the latest api-diff is for .NET 10 GA, it will automatically generate a diff for .NET 11 Preview 1.
 
 ```powershell
+.\RunApiDiff.ps1
+```
+
+## Parameters
+
+### Version Parameters
+
+By default the script assumes a diff will be produced for the next preview. When no version information is provided, the script scans existing `api-diff` folders in the repository to find the latest version and infers the next one in the progression (preview.1 → preview.2 → ... → preview.7 → rc.1 → rc.2 → GA → next major preview.1). When `PreviousVersion` or `CurrentVersion` is provided, the `MajorMinor` and `PrereleaseLabel` values are extracted from it automatically.
+
+| Parameter | Description | Default |
+|---|---|---|
+| `PreviousVersion` | Exact package version for the "before" comparison (e.g., `10.0.0-preview.7.25380.108`). MajorMinor and PrereleaseLabel are extracted automatically. | *(empty — inferred or searched)* |
+| `CurrentVersion` | Exact package version for the "after" comparison (e.g., `10.0.0-rc.1.25451.107`). MajorMinor and PrereleaseLabel are extracted automatically. | *(empty — inferred or searched)* |
+| `PreviousMajorMinor` | The "before" .NET major.minor version (e.g., `10.0`) | Inferred from api-diffs, extracted from `PreviousVersion`, or discovered from `PreviousNuGetFeed` |
+| `PreviousPrereleaseLabel` | Prerelease label for the "before" version (e.g., `preview.7`, `rc.1`). Omit for GA. | Inferred from api-diffs, extracted from `PreviousVersion`, or discovered from `PreviousNuGetFeed` |
+| `CurrentMajorMinor` | The "after" .NET major.minor version (e.g., `10.0`) | Inferred from api-diffs, extracted from `CurrentVersion`, or discovered from `CurrentNuGetFeed` |
+| `CurrentPrereleaseLabel` | Prerelease label for the "after" version (e.g., `preview.7`, `rc.1`). Omit for GA. | Inferred from api-diffs, extracted from `CurrentVersion`, or discovered from `CurrentNuGetFeed` |
+
+### Feed Parameters
+
+| Parameter | Description | Default |
+|---|---|---|
+| `CurrentNuGetFeed` | NuGet feed URL for downloading "after" packages | Constructed from `CurrentMajorMinor`: `https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet{MAJOR}/nuget/v3/index.json` |
+| `PreviousNuGetFeed` | NuGet feed URL for downloading "before" packages | Constructed from `PreviousMajorMinor`: `https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet{MAJOR}/nuget/v3/index.json` |
+
+### Path Parameters
+
+| Parameter | Description | Default |
+|---|---|---|
+| `CoreRepo` | Path to your local clone of the dotnet/core repo | Git repo root relative to the script |
+| `TmpFolder` | Working directory for downloaded and extracted packages | Auto-created temp directory |
+| `AttributesToExcludeFilePath` | Path to attributes exclusion file | `ApiDiffAttributesToExclude.txt` (same folder as script) |
+| `AssembliesToExcludeFilePath` | Path to assemblies exclusion file | `ApiDiffAssembliesToExclude.txt` (same folder as script) |
+
+### Switches
+
+| Parameter | Description |
+|---|---|
+| `ExcludeNetCore` | Skip the Microsoft.NETCore.App comparison |
+| `ExcludeAspNetCore` | Skip the Microsoft.AspNetCore.App comparison |
+| `ExcludeWindowsDesktop` | Skip the Microsoft.WindowsDesktop.App comparison |
+| `InstallApiDiff` | Install or update the ApiDiff tool before running |
+
+## Examples
+
+```powershell
+# Infer the previous version from the most recent existing api-diff
+# and infer the the current version to be the next version after it
+.\RunApiDiff.ps1
+
+# Specify only the current version; previous is inferred from existing api-diffs
+.\RunApiDiff.ps1 -CurrentMajorMinor 11.0 -CurrentPrereleaseLabel preview.2
+
+# Specify both versions explicitly
+.\RunApiDiff.ps1 `
+   -PreviousMajorMinor 10.0 -PreviousPrereleaseLabel preview.7 `
+   -CurrentMajorMinor 10.0 -CurrentPrereleaseLabel rc.1
+
+# Use exact NuGet package versions (MajorMinor and PrereleaseLabel are extracted automatically)
+.\RunApiDiff.ps1 `
+   -PreviousVersion "10.0.0-preview.7.25380.108" `
+   -CurrentVersion "10.0.0-rc.1.25451.107"
+
+# Use a custom feed for the current version's packages
 .\RunApiDiff.ps1 `
-   -PreviousDotNetVersion 10.0 `
-   -PreviousPreviewOrRC preview `
-   -PreviousPreviewNumberVersion 1 `
-   -CurrentDotNetVersion 10.0 `
-   -CurrentPreviewOrRC preview `
-   -CurrentPreviewNumberVersion 2 `
-   -CoreRepo D:\core\ `
-   -TmpFolder D:\tmp\
+   -CurrentNuGetFeed "https://pkgs.dev.azure.com/dnceng/public/_packaging/dotnet11/nuget/v3/index.json"
 ```
 
-Example of what this script generates: [API diff between .NET 10.0 Preview1 and .NET 10 Preview2](https://github.com/dotnet/core/pull/9771)
+Example of what this script generates: [API diff between .NET 10 GA and .NET 11 Preview 1 (dotnet/core#10240)](https://github.com/dotnet/core/pull/10240/changes)