AI Agent and SKILL for What's New gen from Release Notes by wadepickett · Pull Request #36863 · dotnet/AspNetCore.Docs

wadepickett · 2026-03-10T23:22:56Z

Overview for Reviewers

This PR adds two files that work together to automate generating the "What's New in ASP.NET Core" article content from .NET preview release notes:

Agent: whats-new-from-release-notes.agent.md
- Orchestrates the full end-to-end workflow
- Reads source release notes from dotnet/core
- Compares them against what's already been processed in dotnet/AspNetCore.Docs
- Creates new include files for unprocessed features
- Wires [!INCLUDE] directives into the correct sections of the What's New article
- Updates front matter and validates the result
- Supports an incremental mode to handle only what changed since the last run
Skill: whats-new-include-content-rules/SKILL.md
- Defines how each include file should be written
- The agent delegates to this skill for all content-level decisions:
  - File naming conventions (-preview{N} suffix)
  - Heading levels (H3 only)
  - <xref:> API reference format
  - Link style (relative for Microsoft Learn, absolute for GitHub)
  - Phrasing rules (present tense, imperative voice, "For more information, see" pattern)
  - Exclusions (no Blazor, no bug fixes)
  - Preservation of Breaking Change labels and community contributor acknowledgments
- Encodes corrections from past PR reviews so the same mistakes aren't repeated

File	Status	Description
`.github/agents/whats-new-from-release-notes.agent.md`	✨ Added	Agent — orchestrates the workflow end-to-end
`.github/skills/whats-new-include-content-rules/SKILL.md`	✨ Added	Skill — content rules and formatting standards

In short: The agent decides what to do and when. The skill decides how the content should look. They are separated so the content rules can be reused independently (e.g., by a human author or a different agent) without re-implementing the orchestration logic.

Agent workflow

Step	What it does
Step 0: Gather context	Reads source release notes from `dotnet/core`, reads the current What's New article, lists existing include files, compares source vs. existing, and reports the delta (new / updated / already covered).
Step 1: Create include files	Generates one include file per feature, following all rules from the skill.
Step 2: Update the What's New article	Adds `[!INCLUDE]` directives in the correct product-area sections, updates `ms.date`, preserves the Breaking Changes section.
Step 3: Validate	Runs the skill's 12-point validation checklist plus article-level checks (date, include placement, section mapping).
Incremental mode	Can be re-invoked after release notes are revised — detects and applies only the delta.

Key content rules encoded in the skill

Filenames must be lowercase, hyphenated, and end with -preview{N}
One file per feature (exception: performance improvements combined into one file)
No Blazor content (handled separately by the Blazor team)
<xref:fully.qualified.name> for API references — not backtick inline code
Relative paths for Microsoft Learn links; absolute URLs for GitHub/external
Present tense, imperative voice, "For more information, see" phrasing
Preserve Breaking Change designations and community contributor thank-yous
Include files have no YAML front matter

Internal previews

📄 File	🔗 Preview link
.github/agents/whats-new-from-release-notes.agent.md	What's New Release Notes Agent for ASP.NET Core Documentation
.github/skills/whats-new-include-content-rules/SKILL.md	.github/skills/whats-new-include-content-rules/SKILL

Copilot

Pull request overview

Adds a GitHub Copilot agent + supporting skill to automate generating “What’s New in ASP.NET Core” include content from dotnet/core preview release notes, including incremental/delta updates.

Changes:

Added a new agent that orchestrates reading release notes, diffing against existing includes, generating new include files, and wiring [!INCLUDE] directives into the What’s New article.
Added a skill that defines standardized include-file content rules (headings, <xref:> usage, link formats, phrasing, exclusions) and a validation checklist.

Reviewed changes

Copilot reviewed 2 out of 2 changed files in this pull request and generated 4 comments.

File	Description
`.github/agents/whats-new-from-release-notes.agent.md`	New agent prompt for end-to-end “What’s New” generation/update workflow.
`.github/skills/whats-new-include-content-rules/SKILL.md`	New skill defining include-file formatting/content rules and validation checklist.

You can also share your feedback on Copilot code review. Take the survey.

.github/agents/whats-new-from-release-notes.agent.md

.github/skills/whats-new-include-content-rules/SKILL.md

.github/agents/whats-new-from-release-notes.agent.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Fix formatting of code block for OpenAPI version update. Removed hidden character

Copilot

Pull request overview

Copilot reviewed 2 out of 2 changed files in this pull request and generated 2 comments.

You can also share your feedback on Copilot code review. Take the survey.

.github/agents/whats-new-from-release-notes.agent.md

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

…/dotnet/AspNetCore.Docs into wadepickett/36862AiAgentWhatsNew

tdykstra

Looks great, I'm anxious to see what it generates!

tdykstra · 2026-03-11T21:57:04Z

.github/agents/whats-new-from-release-notes.agent.md

+Before creating any files, you MUST:
+
+1. **Read the source release notes** from `dotnet/core` at the specified branch:
+   `release-notes/{VERSION}/preview/{PREVIEW}/aspnetcore.md`


should version here be major version as in subsequent lines?

.github/skills/whats-new-include-content-rules/SKILL.md

tdykstra · 2026-03-11T22:25:58Z

.github/skills/whats-new-include-content-rules/SKILL.md

+* **Wrong**: `` `AddOpenApi()` ``
+* **Correct**: `<xref:Microsoft.Extensions.DependencyInjection.OpenApiServiceCollectionExtensions.AddOpenApi%2A>`
+* **Wrong**: `` `BadHttpRequestException` ``
+* **Correct**: `<xref:Microsoft.AspNetCore.Http.BadHttpRequestException>`
+* When referencing an API type or method, always use `<xref:fully.qualified.name>`


If the Api is new, xref format won't work, You could have them link to the source code instead.

Great point. I wonder if it is capable of testing first for the xref and if that does not work, fall back to the source code and make an comment to update to xref later as the api becomes available.

.github/skills/whats-new-include-content-rules/SKILL.md

meaghanlewis

This looks great @wadepickett! I left a few suggestions and questions for you to consider.

meaghanlewis · 2026-03-11T23:26:03Z

.github/skills/whats-new-include-content-rules/SKILL.md

+
+### Links — use relative paths for Microsoft Learn
+
+* **Wrong**: `[Breaking changes in .NET]([/dotnet/core/compatibility/breaking-changes](https://learn.microsoft.com/dotnet/core/compatibility/breaking-changes))`


Suggested change

* **Wrong**: `[Breaking changes in .NET]([/dotnet/core/compatibility/breaking-changes](https://learn.microsoft.com/dotnet/core/compatibility/breaking-changes))`

* **Wrong**: `[Breaking changes in .NET](https://learn.microsoft.com/dotnet/core/compatibility/breaking-changes)`

Is this what you meant here instead?

I provided an example of what not to do , because it kept trying to do it that way during testing.

meaghanlewis · 2026-03-11T23:30:58Z

.github/skills/whats-new-include-content-rules/SKILL.md

+
+### Phrasing and style (lessons from reviewer feedback)
+
+* Use **"For more information, see [link text](url)."** — not em-dash + "see … for details."


Suggested change

* Use **"For more information, see [link text](url)."** — not em-dash + "see … for details."

* Use **"For more information, see [link text](url)."**, not "see [link text](url) for details."

This better follows the style of the other list items in this section. Also, I don't understand the em-dash part of this sentence. An example could help.

I goofed this up. Basically it was trying to say, don't use an em-dash. It should have had a wrong example using a em-dash and then a correct example not using it. Thanks for pointing it out. I need to fix.

.github/agents/whats-new-from-release-notes.agent.md

meaghanlewis · 2026-03-11T23:46:26Z

.github/agents/whats-new-from-release-notes.agent.md

+Before reading any files, resolve the following parameters. If the invoker
+provided explicit values, use them. Otherwise, auto-discover.
+
+| Parameter | Required | Default | Description |


Should the same table from the inputs section be here as well?

meaghanlewis · 2026-03-11T23:48:24Z

.github/agents/whats-new-from-release-notes.agent.md

+
+- [ ] The What's New article `ms.date` is set to today's date
+- [ ] All `[!INCLUDE]` directives are correctly placed with blank lines around them
+- [ ] Section mapping matches the table above


Can you specify or link to the section that has the table instead of using above.

Adding suggestions from MeaghanLewis Co-authored-by: Meaghan Osagie (Lewis) <moneikmarie@gmail.com>

I Agentfor What's New gen from Release Notes

7a44dc2

wadepickett self-assigned this Mar 10, 2026

wadepickett added 2 commits March 11, 2026 09:13

Format improvments

03163ef

Refactored to seperate SKILLS.md and Agent

e6a8a12

wadepickett marked this pull request as ready for review March 11, 2026 18:49

wadepickett requested review from Copilot and tdykstra March 11, 2026 18:50

Copilot started reviewing on behalf of wadepickett March 11, 2026 18:51 View session

wadepickett requested a review from meaghanlewis March 11, 2026 18:51

wadepickett changed the title ~~AI agent for What's New gen from Release Notes~~ AI Agent and SKILL for What's New gen from Release Notes Mar 11, 2026

Copilot AI reviewed Mar 11, 2026

View reviewed changes

wadepickett and others added 4 commits March 11, 2026 12:13

Apply suggestion from @Copilot

341745b

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Apply suggestion from @Copilot

8a0f2d1

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Apply suggestion from @Copilot

e1fc510

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Correct code block formatting in SKILL.md

f904a4a

Fix formatting of code block for OpenAPI version update. Removed hidden character

wadepickett requested a review from Copilot March 11, 2026 19:23

Copilot started reviewing on behalf of wadepickett March 11, 2026 19:24 View session

Copilot AI reviewed Mar 11, 2026

View reviewed changes

.github/agents/whats-new-from-release-notes.agent.md Outdated Show resolved Hide resolved

.github/agents/whats-new-from-release-notes.agent.md Outdated Show resolved Hide resolved

wadepickett and others added 3 commits March 11, 2026 12:32

Apply suggestions from code review

5224fbe

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Account for PR source changes

2f66517

Merge branch 'wadepickett/36862AiAgentWhatsNew' of https://github.com…

f487568

…/dotnet/AspNetCore.Docs into wadepickett/36862AiAgentWhatsNew

tdykstra approved these changes Mar 11, 2026

View reviewed changes

Add handling for varying Release Notes naming.

19f7ba1

meaghanlewis approved these changes Mar 11, 2026

View reviewed changes

wadepickett and others added 2 commits March 11, 2026 17:08

Updates per tdykstra

463ef61

Apply suggestions from code review

16a2d29

Adding suggestions from MeaghanLewis Co-authored-by: Meaghan Osagie (Lewis) <moneikmarie@gmail.com>


		### Links — use relative paths for Microsoft Learn

		* Wrong: `[Breaking changes in .NET]([/dotnet/core/compatibility/breaking-changes](https://learn.microsoft.com/dotnet/core/compatibility/breaking-changes))`


		### Phrasing and style (lessons from reviewer feedback)

		* Use "For more information, see [link text](url)." — not em-dash + "see … for details."

Conversation

wadepickett commented Mar 10, 2026 • edited by github-actions bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Overview for Reviewers

Agent workflow

Key content rules encoded in the skill

Internal previews

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

tdykstra left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

meaghanlewis left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

wadepickett commented Mar 10, 2026 •

edited by github-actions bot

Loading