Add release-notes, breaking-changes, and bump-version Copilot skills

.github/skills/breaking-changes/SKILL.md

@@ -0,0 +1,71 @@
+---
+name: breaking-changes
+description: Audit pull requests for breaking changes in the C# MCP SDK. Examines PR descriptions, review comments, and diffs to identify API and behavioral breaking changes, then reconciles labels with user confirmation. Use when asked to audit breaking changes, check for breaking changes, or review a set of PRs for breaking impact.
+compatibility: Requires gh CLI with repo access and GitHub API access for PR details, review history, and labels.
+---
+
+# Breaking Change Audit
+
+Audit pull requests in the `modelcontextprotocol/csharp-sdk` repository for breaking changes. This skill examines a range of commits, identifies API and behavioral breaking changes, assesses their impact, reconciles `breaking-change` labels, and returns structured results.
+
+## Input
+
+The user provides a commit range in any of these forms:
+- `tag..HEAD` (e.g. `v0.8.0-preview.1..HEAD`)
+- `tag..tag` (e.g. `v0.8.0-preview.1..v0.9.0-preview.1`)
+- `sha..sha`
+- `tag..sha` or `sha..HEAD`
+
+If no range is provided, ask the user to specify one.
+
+Use the GitHub API to get the full list of PRs merged within the specified range.
+
+## Process
+
+### Step 1: Examine Every PR
+
+For each PR in the range, study:
+- PR description and linked issues
+- Full review and comment history
+- Complete code diff
+
+Look for both categories of breaking changes:
+- **API (compile-time)** — changes to public type signatures, parameter types, return types, removed members, sealed types, new obsoletion attributes, etc.
+- **Behavioral (runtime)** — new/changed exceptions, altered return values, changed defaults, modified event ordering, serialization changes, etc.
+
+See [references/classification.md](references/classification.md) for the full classification guide.
+
+### Step 2: Assess Impact
+
+For each identified breaking change, assess:
+- **Breadth** — how many consumers are likely affected (widely-used type vs. obscure API)
+- **Severity** — compile-time break (immediate build failure) vs. behavioral (subtle runtime difference)
+- **Migration** — straightforward fix vs. significant code changes required
+
+This assessment informs how breaking changes are ordered when presented (most impactful first).
+
+### Step 3: Reconcile Labels
+
+Compare findings against existing `breaking-change` labels on PRs.
+
+Present mismatches to the user interactively:
+
+- **Unlabeled but appears breaking** → explain why the PR appears breaking, ask user to confirm. If confirmed: apply the `breaking-change` label and ask the user whether to comment on the PR explaining the addition.
+- **Labeled but does not appear breaking** → explain why, ask user to confirm removal. If confirmed: remove the label and ask the user whether to comment on the PR explaining the removal.
+
+### Step 4: Present Results
+
+Present the final list of confirmed breaking changes, sorted from most impactful to least, with:
+- PR number and title
+- Classification (API or behavioral)
+- Impact assessment summary
+- 1-2 bullet description of what breaks and migration guidance
+
+## Output
+
+The audit produces a structured list of breaking changes that can be consumed by other skills (e.g. the release-notes skill) or presented directly to the user.
+
+Each entry contains:
+- PR number and description
+- Impact ranking (most → least impactful)
+- Detail bullets describing the break and migration path

.github/skills/breaking-changes/references/classification.md

@@ -0,0 +1,78 @@
+# Breaking Change Classification Guide
+
+This guide defines how to identify and classify breaking changes in the C# MCP SDK. It is derived from the [dotnet/runtime breaking change guidelines](https://github.com/dotnet/runtime/blob/main/docs/coding-guidelines/breaking-changes.md).
+
+## Two Categories of Breaking Changes
+
+### API Breaking Changes (Compile-Time)
+Changes that alter the public API surface in ways that break existing code at compile time:
+
+- **Renaming or removing** a public type, member, or parameter
+- **Changing the return type** of a method or property
+- **Changing parameter types, order, or count** on a public method
+- **Sealing** a type that was previously unsealed (when it has accessible constructors)
+- **Making a virtual member abstract**
+- **Adding `abstract` to a member** when the type has accessible constructors and is not sealed
+- **Removing an interface** from a type's implementation
+- **Changing the value** of a public constant or enum member
+- **Changing the underlying type** of an enum
+- **Adding `readonly` to a field**
+- **Removing `params` from a parameter**
+- **Adding/removing `in`, `out`, or `ref`** parameter modifiers
+- **Renaming a parameter** (breaks named arguments and late-binding)
+- **Adding the `[Obsolete]` attribute** or changing its diagnostic ID
+- **Adding the `[Experimental]` attribute** or changing its diagnostic ID
+- **Removing accessibility** (making a public/protected member less visible)
+
+### Behavioral Breaking Changes (Runtime)
+Changes that don't break compilation but alter observable behavior:
+
+- **Throwing a new/different exception type** in an existing scenario (unless it's a more derived type)
+- **No longer throwing an exception** that was previously thrown
+- **Changing return values** for existing inputs
+- **Decreasing the range of accepted values** for a parameter
+- **Changing default values** for properties, fields, or parameters
+- **Changing the order of events** being fired
+- **Removing the raising of an event**
+- **Changing timing/order** of operations
+- **Changing parsing behavior** and throwing new errors
+- **Changing serialization format** or adding new fields to serialized types
+
+## Classification Buckets
+
+### Bucket 1: Clear Public Contract Violation
+Obvious breaking changes to the public API shape. **Always flag these.**
+
+### Bucket 2: Reasonable Grey Area
+Behavioral changes that customers would have reasonably depended on. **Flag and discuss with user.**
+
+### Bucket 3: Unlikely Grey Area
+Behavioral changes that customers could have depended on but probably wouldn't (e.g., corner case corrections). **Flag with lower confidence.**
+
+### Bucket 4: Clearly Non-Public
+Changes to internal surface or behavior (e.g., internal APIs, private reflection). **Generally not flagged** unless they could affect ecosystem tools.
+
+## Compatibility Switches
+
+When a breaking change includes an `AppContext` switch or other opt-in/opt-out mechanism, always note it in the migration guidance. Search for `AppContext.TryGetSwitch`, `DOTNET_` environment variables, and similar compat patterns in the diff. Include the switch name and the value that alters the behavior:
+
+```
+* Compat switch: `ModelContextProtocol.AspNetCore.AllowNewSessionForNonInitializeRequests` = `true` restores previous behavior
+```
+
+## What to Study for Each PR
+
+For every PR in the range, examine:
+
+1. **PR description** — Authors often describe breaking changes here
+2. **Linked issues** — May contain discussion about breaking impact
+3. **Review comments** — Reviewers may have flagged breaking concerns
+4. **Code diff** — Look at changes to:
+   - Public type/member signatures
+   - Exception throwing patterns
+   - Default values and constants
+   - Return value changes
+   - Parameter validation changes
+   - Attribute changes (`[Obsolete]`, `[Experimental]`, etc.)
+   - `AppContext.TryGetSwitch` or environment variable compat switches
+5. **Labels** — Check if `breaking-change` is already applied

.github/skills/bump-version/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: bump-version
+description: Bump the SDK version after publishing a release. Reads the current version from src/Directory.Build.props, suggests the next minor version, and creates a pull request with the change. Use when asked to bump the version, prepare for the next release, or increment the version number.
+compatibility: Requires gh CLI with repo access for creating branches and pull requests.
+---
+
+# Bump Version
+
+Bump the SDK version in `src/Directory.Build.props` after publishing a release and create a pull request with the change.
+
+## Process
+
+### Step 1: Read Current Version
+
+Read `src/Directory.Build.props` on the default branch and extract:
+- `<VersionPrefix>` — the `MAJOR.MINOR.PATCH` version
+- `<VersionSuffix>` — the prerelease suffix (e.g. `preview.1`), if present
+
+Display the current version to the user: `{VersionPrefix}-{VersionSuffix}` or `{VersionPrefix}` if no suffix.
+
+### Step 2: Determine Next Version
+
+If the user provided a target version in their prompt, use it. Otherwise, suggest the next **minor** version with the same suffix pattern:
+
+- Current `0.9.0` with suffix `preview.1` → suggest `0.10.0-preview.1`
+- Current `1.0.0` with no suffix → suggest `1.1.0`
+- Current `1.2.3` with suffix `rc.1` → suggest `1.3.0-rc.1`
+
+Present the suggestion and let the user confirm or provide an alternative. Parse the confirmed version into its `VersionPrefix` and `VersionSuffix` components.
+
+### Step 3: Create Pull Request
+
+1. Create a new branch named `bump-version-to-{version}` (e.g. `bump-version-to-0.10.0-preview.1`) from the default branch
+2. Update `src/Directory.Build.props`:
+   - Set `<VersionPrefix>` to the new prefix
+   - Set `<VersionSuffix>` to the new suffix, or remove the element if there is no suffix
+3. Commit with message: `Bump version to {version}`
+4. Push the branch and create a pull request:
+   - **Title**: `Bump version to {version}`
+   - **Label**: `infrastructure`
+   - **Base**: default branch
+
+### Step 4: Confirm
+
+Display the pull request URL to the user.

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

@@ -0,0 +1,154 @@
+---
+name: release-notes
+description: Prepare release notes for the C# MCP SDK. Categorizes PRs, audits breaking changes, reconciles labels, attributes co-authors, identifies acknowledgements, and creates or updates a draft GitHub release. Use when asked to prepare a release, write release notes, update release notes, create a changelog, or summarize a version.
+compatibility: Requires gh CLI with repo access and GitHub API access for PR details, timeline events, and commit trailers.
+---
+
+# Release Notes Preparation
+
+Prepare polished, categorized release notes for the `modelcontextprotocol/csharp-sdk` repository. This skill determines the version from the repository's build properties, gathers all data from GitHub, and creates or updates a **draft** release.
+
+> **Safety: This skill only creates and updates draft releases. It must never publish a release.** If the user asks to publish, decline and instruct them to publish manually through the GitHub UI.
+
+## Process
+
+Work through each step sequentially. Present findings at each step and get user confirmation before proceeding. Skip any step that has no applicable items.
+
+### Step 1: Determine Version and Target
+
+The user may provide:
+- **A git ref** (commit SHA, branch, or tag) — use as the target commit
+- **An existing draft release** (URL or tag) — use its target commit
+- **No context** — show the last 5 commits on `main` (noting HEAD) and offer the option to enter a branch or tag name instead
+
+Once the target is established:
+1. Read `src/Directory.Build.props` **at the target commit**. Extract `<VersionPrefix>` and `<VersionSuffix>`. The tag and title are `v{VersionPrefix}-{VersionSuffix}`, or `v{VersionPrefix}` if no suffix. Pre-release if `VersionSuffix` is present.
+2. Check for an existing draft release matching this tag.
+3. Determine the previous release tag from `gh release list` (most recent published release).
+4. Get the full list of PRs merged between the previous release tag and the target commit.
+
+### Step 2: Categorize and Attribute
+
+Sort every PR into one of three categories. See [references/categorization.md](references/categorization.md) for detailed guidance.
+
+| Category | Content |
+|----------|---------|
+| **What's Changed** | Features, bug fixes, improvements, breaking changes |
+| **Documentation Updates** | PRs whose sole purpose is documentation |
+| **Test Improvements** | Adding, fixing, or unskipping tests; flaky test repairs |
+| **Repository Infrastructure Updates** | CI/CD, dependency bumps, version bumps, build system |
+
+**Entry format** — `* Description #PR by @author` with co-authors when present:
+```
+* Description #PR by @author
+* Description #PR by @author (co-authored by @user1 @Copilot)
+```
+
+**Attribution rules:**
+- Harvest `Co-authored-by` trailers from all commits in each PR's merge commit
+- For Copilot-authored PRs, check the `copilot_work_started` timeline event to identify the triggering user. That person becomes the primary author; `@Copilot` becomes a co-author
+- Omit the co-author parenthetical when there are none
+- Sort entries within each section by merge date (chronological)
+
+### Step 3: Breaking Change Audit
+
+Invoke the **breaking-changes** skill with the commit range from the previous release tag to the target commit. That skill handles the full audit — examining every PR, assessing impact, reconciling labels, and getting user confirmation.
+
+Use the results (confirmed breaking changes with impact ordering and detail bullets) in the remaining steps.
+
+### Step 4: Review Sections
+
+Present each section for user review:
+1. **Breaking Changes** — sorted most → least impactful (from Step 3 results)
+2. **What's Changed** — chronological; includes breaking change PRs
+3. **Documentation Updates** — chronological
+4. **Test Improvements** — chronological
+5. **Repository Infrastructure Updates** — chronological
+
+### Step 5: Acknowledgements
+
+Identify contributors beyond PR authors:
+1. **New contributors** — first contribution to the repository in this release
+2. **Issue reporters** — users who submitted issues resolved by PRs in this release (cite the resolving PR)
+3. **PR reviewers** — users who reviewed PRs, excluding PR authors and bots
+
+Exclude anyone already listed as a PR author. Format:
+```
+* @user made their first contribution in #PR
+* @user submitted issue #1234 (resolved by #5678)
+* PR reviewers: @user1 @user2 @user3
+```
+Reviewers go on a single bullet, sorted by number of PRs reviewed (most first), without citing the count.
+
+### Step 6: Final Assembly
+
+1. **Preamble** — summarize the release theme. If there are breaking changes, mention them and link to the [C# SDK Versioning](https://modelcontextprotocol.github.io/csharp-sdk/versioning.html) docs. Do not repeat preamble text under the Breaking Changes heading. Let the user revise or omit.
+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 7: Create or Update Draft Release
+
+Display release metadata for user review:
+- **Title / Tag**: e.g. `v0.9.0-preview.1`
+- **Target**: commit SHA, its message, and associated PR link
+- **Newer commits**: whether `main` has commits beyond the target
+- **Pre-release**: yes/no (based on `VersionSuffix`)
+
+After confirmation:
+- **No existing draft** → create with `gh release create --draft` (always `--draft`)
+- **Existing draft** → update the release notes body only
+- **Never publish.** Never change pre-release state, title, tag, or other metadata on an existing draft.
+
+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 8: 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.
+
+## Edge Cases
+
+- **PR spans categories**: categorize by primary intent
+- **Copilot timeline missing**: fall back to `Co-authored-by` trailers; if still unclear, use `@Copilot` as primary author
+- **Draft tag changes**: re-fetch the tag before each `gh release edit`
+- **No breaking changes**: omit the Breaking Changes section and breaking change preamble language
+- **Single breaking change**: use the same numbered format as multiple
+
+## Release Notes Template
+
+Omit empty sections:
+
+```markdown
+[Preamble — release theme, breaking changes note, versioning docs link]
+
+## Breaking Changes
+
+1. **Description #PR**
+   * Detail of the break
+   * Migration guidance
+
+## What's Changed
+
+* Description #PR by @author (co-authored by @user1 @Copilot)
+
+## Documentation Updates
+
+* Description #PR by @author (co-authored by @user1 @Copilot)
+
+## Test Improvements
+
+* Description #PR by @author (co-authored by @user1 @Copilot)
+
+## Repository Infrastructure Updates
+
+* Description #PR by @author (co-authored by @user1 @Copilot)
+
+## Acknowledgements
+
+* @user made their first contribution in #PR
+* @user submitted issue #1234 (resolved by #5678)
+* @user1 @user2 @user3 reviewed pull requests
+
+**Full Changelog**: previous-tag...new-tag
+```