Add README code sample validation step to release-notes skill

.github/skills/release-notes/SKILL.md

@@ -61,7 +61,19 @@ When **editing an existing release**, also extract any breaking changes already
 
 Use the results (confirmed breaking changes with impact ordering and detail bullets) in the remaining steps.
 
-### Step 4: Review Sections
+### Step 4: Validate README Code Samples
+
+Verify that all C# code samples in the package README files compile against the current SDK at the target commit. Follow [references/readme-snippets.md](references/readme-snippets.md) for the full procedure.
+
+1. Extract `csharp`-fenced code blocks from `README.md`, `src/ModelContextProtocol.Core/README.md`, and `src/ModelContextProtocol.AspNetCore/README.md`
+2. Create a temporary test project at `tests/ReadmeSnippetValidation/` that references the SDK projects
+3. Wrap each code block in a compilable method, applying fixups for incomplete snippets (replace `...` with `null!`, add common usings)
+4. Build the project with `dotnet build`
+5. Report results — classify any failures as API mismatches (README bugs) or structural fragments
+6. If API mismatches are found, propose fixes and get user confirmation before editing READMEs
+7. Delete the temporary `tests/ReadmeSnippetValidation/` directory
+
+### Step 5: Review Sections
 
 Present each section for user review:
 1. **Breaking Changes** — sorted most → least impactful (from Step 3 results)
@@ -70,7 +82,7 @@ Present each section for user review:
 4. **Test Improvements** — chronological
 5. **Repository Infrastructure Updates** — chronological
 
-### Step 5: Acknowledgements
+### Step 6: Acknowledgements
 
 Identify contributors beyond PR authors:
 1. **New contributors** — first contribution to the repository in this release
@@ -85,7 +97,7 @@ Exclude anyone already listed as a PR author. Format:
 ```
 Reviewers go on a single bullet, sorted by number of PRs reviewed (most first), without citing the count.
 
-### Step 6: Preamble
+### Step 7: Preamble
 
 Every release **must** have a preamble — a short paragraph summarizing the release theme that appears before the first `##` heading. The preamble is not optional. The preamble may mention the presence of breaking changes as part of the theme summary, but the versioning documentation link belongs under the Breaking Changes heading (see template), not in the preamble.
 
@@ -94,15 +106,15 @@ Every release **must** have a preamble — a short paragraph summarizing the rel
 
 Present the options and let the user choose one, edit one, or enter their own text or markdown.
 
-### Step 7: Final Assembly
+### Step 8: Final Assembly
 
 1. Combine the confirmed preamble with all sections from previous steps.
 2. **Notable callouts** — only if something is extraordinarily noteworthy.
 3. Present the **complete release notes** for user approval.
 
 Follow [references/formatting.md](references/formatting.md) when composing and updating the release body.
 
-### Step 8: Create or Update Draft Release
+### Step 9: Create or Update Draft Release
 
 Display release metadata for user review:
 - **Title / Tag**: e.g. `v0.9.0-preview.1`
@@ -117,7 +129,7 @@ After confirmation:
 
 When the user requests revisions after the initial update, always rewrite the complete body as a file — never perform in-place string replacements. See [references/formatting.md](references/formatting.md).
 
-### Step 9: Bump Version
+### Step 10: Bump Version
 
 After the draft release is created or updated, inform the user that the draft release is now associated with a known target commit (state the short SHA and commit message) and recommend proceeding with a version bump. Ask if they want to create a pull request to bump the version for the next release. If yes, invoke the **bump-version** skill and let it handle determining or requesting the target version number.
 

.github/skills/release-notes/references/readme-snippets.md

@@ -0,0 +1,143 @@
+# README Code Sample Validation
+
+This reference describes how to validate that C# code samples in README files compile against the current SDK.
+
+## Which READMEs to Validate
+
+Validate code samples from the **package README** files — these are shipped with NuGet packages and are the primary documentation users see:
+
+| README | Package |
+|--------|---------|
+| `README.md` (root) | ModelContextProtocol |
+| `src/ModelContextProtocol.Core/README.md` | ModelContextProtocol.Core |
+| `src/ModelContextProtocol.AspNetCore/README.md` | ModelContextProtocol.AspNetCore |
+
+Sample README files (`samples/*/README.md`) are excluded — the samples themselves are buildable projects and are validated by CI.
+
+## What to Extract
+
+Extract only fenced code blocks tagged as `csharp` (` ```csharp `). Skip blocks tagged as plain ` ``` ` (shell commands, install instructions) or any other language.
+
+### Handling Incomplete Snippets
+
+README samples are often **incomplete** — they use `...` for placeholder values, omit `using` directives, or show only a method body. The validation wrapper must account for this:
+
+- **Placeholder expressions** like `IChatClient chatClient = ...;` — replace `...` on the right-hand side of assignments with `null!`
+- **Missing usings** — the wrapper file supplies all common namespaces (see template below)
+- **Top-level statements** — wrap in an `async Task` method so `await` works
+- **Suppressed warnings** — disable CS1998 (async without await), CS8321 (unused local function), and similar non-substantive warnings
+
+### Snippets That Cannot Be Validated
+
+Some code blocks are illustrative fragments that cannot compile even with wrappers (e.g., partial class definitions shown in isolation, pseudo-code). If a snippet fails to compile after applying the standard fixups, examine the error:
+
+- **API mismatch** (missing member, wrong type, wrong signature) → this is a **real bug** in the README that must be reported and fixed
+- **Structural issue** (missing context, incomplete fragment) → exclude this specific snippet from validation with a comment explaining why
+
+## Test Project Approach
+
+Create a **temporary** test project that references the SDK projects, wraps each README's code samples in compilable methods, and builds.
+
+### Project File Template
+
+```xml
+<Project Sdk="Microsoft.NET.Sdk">
+  <PropertyGroup>
+    <TargetFramework>net10.0</TargetFramework>
+    <OutputType>Library</OutputType>
+    <Nullable>enable</Nullable>
+    <ImplicitUsings>enable</ImplicitUsings>
+    <LangVersion>preview</LangVersion>
+    <NoWarn>CS1998;CS8321;CS0168;CS0219;CS1591;CS8602</NoWarn>
+  </PropertyGroup>
+  <ItemGroup>
+    <ProjectReference Include="..\..\src\ModelContextProtocol\ModelContextProtocol.csproj" />
+    <ProjectReference Include="..\..\src\ModelContextProtocol.AspNetCore\ModelContextProtocol.AspNetCore.csproj" />
+  </ItemGroup>
+</Project>
+```
+
+Place the project at `tests/ReadmeSnippetValidation/ReadmeSnippetValidation.csproj`.
+
+### Source File Template
+
+Create one `.cs` file per README. Each file wraps the README's code blocks in static methods inside a class. Use this pattern:
+
+```csharp
+#pragma warning disable CS1998
+#pragma warning disable CS8321
+
+using Microsoft.AspNetCore.Builder;
+using Microsoft.Extensions.AI;
+using Microsoft.Extensions.DependencyInjection;
+using Microsoft.Extensions.Hosting;
+using Microsoft.Extensions.Logging;
+using ModelContextProtocol;
+using ModelContextProtocol.Client;
+using ModelContextProtocol.Protocol;
+using ModelContextProtocol.Server;
+using System.ComponentModel;
+using System.Text.Json;
+
+namespace ReadmeSnippetValidation;
+
+public static class RootReadmeSamples
+{
+    // Snippet 1: Client example
+    public static async Task ClientExample()
+    {
+        // ... pasted snippet code ...
+    }
+
+    // Snippet 2: Server example
+    public static async Task ServerExample()
+    {
+        // ... pasted snippet code ...
+    }
+
+    // Snippet with attributed types (tools, prompts) go as nested or sibling types
+    [McpServerToolType]
+    public static class EchoTool
+    {
+        [McpServerTool, Description("Echoes the message back to the client.")]
+        public static string Echo(string message) => $"hello {message}";
+    }
+}
+```
+
+### Build Commands
+
+```sh
+# Restore and build the validation project
+dotnet restore tests/ReadmeSnippetValidation/ReadmeSnippetValidation.csproj
+dotnet build tests/ReadmeSnippetValidation/ReadmeSnippetValidation.csproj
+
+### Cleanup
+
+After validation, **always delete** the `tests/ReadmeSnippetValidation/` directory. It must not be committed.
+
+## Reporting Results
+
+### All Snippets Compile
+
+Report success and move to the next step:
+> ✅ All README code samples compile successfully against the current SDK.
+
+### Compilation Failures
+
+For each failure:
+1. Identify the README file and which code block failed
+2. Show the compiler error
+3. Classify the error:
+   - **API mismatch**: The README uses an API that doesn't exist or has a different signature. This indicates the README is outdated and needs updating.
+   - **Structural**: The snippet is a fragment that can't be wrapped. Note it for exclusion.
+4. For API mismatches, investigate the correct current API and propose a fix
+5. Present all findings to the user for confirmation before making any README edits
+
+### Fixing Issues
+
+If the user approves fixes:
+1. Edit the README files directly with minimal, surgical changes
+2. Re-run the validation build to confirm fixes compile
+3. Ensure the overall solution still builds: `dotnet build`
+4. Include the README fixes in the same release or as a prerequisite PR — the user decides