Add an api-proposal Copilot skill

[eiriktsarpalis]

Summary

Adds an api-proposal Copilot skill that automates the prototyping and drafting of API proposals for dotnet/runtime.

Motivation

Evaluating the feasibility of a feature request is frequently the biggest bottleneck when processing API proposals. Before an API can be confidently brought to review, someone needs to:

• Research existing APIs in the target namespace for naming and design consistency
• Build a working prototype that compiles across all target frameworks
• Generate reference assembly source to extract the exact public API surface
• Write tests that validate the design and detect source breaking changes (overload resolution ambiguity, wrong method binding)
• Draft a proposal document that is terse enough for live review yet thorough enough to preempt common reviewer questions

This experimentation work is time-consuming and often deters contributors from turning good ideas into actionable proposals. The goal of this skill is to automate aspects of that original experimentation, so that maintainers can confidently bring API proposals in for review.

What the skill does

The skill guides Copilot through a 6-phase pipeline:

1. Gather Input — Accept a vague idea, issue URL, or API sketch; evaluate workarounds; search for prior proposals
2. Research — Read Framework Design Guidelines and existing APIs in the target namespace
3. Prototype — Implement the API, write tests, build for all TFMs, generate ref source (delegates to the build/test workflow in copilot-instructions.md)
4. Review — Invoke the code-review skill against the prototype diff
5. Draft — Write a terse, empirically grounded proposal following the issue template
6. Publish — Push the prototype and post the proposal as an issue or PR comment

Example invocations

"Draft an API proposal for adding a TryPeek method to PriorityQueue"

"Write an API proposal for https://github.com/dotnet/runtime/issues/XXXXX"

"I have a rough idea: JsonSerializerOptions should support case-insensitive enum deserialization by default. Can you turn this into a complete API proposal?"

"Refine this api-suggestion issue into a full proposal: https://github.com/dotnet/runtime/issues/XXXXX"

"I already have a prototype on branch feature/my-api. Draft a proposal from it."

Example of the skill in action

See #124806 for an end-to-end example of this skill producing a working prototype and proposal.

Files added

• .github/skills/api-proposal/SKILL.md — Main skill definition (phases, validation steps, proposal structure)
• .github/skills/api-proposal/references/api-proposal-checklist.md — Quality checklist for validating proposals before publishing
• .github/skills/api-proposal/references/proposal-examples.md — Curated examples of successful API proposals with annotated lessons

[Copilot]

Pull request overview

This PR adds a new Copilot skill called api-proposal that automates the process of creating prototype-backed API proposals for dotnet/runtime. The skill guides users through a 6-phase pipeline from initial idea to published proposal, with emphasis on empirical validation through working prototypes.

Changes:

• Adds a comprehensive skill definition with detailed workflow phases (gather input, research, prototype, review, draft, publish)
• Provides quality checklist covering all aspects of API proposal validation
• Includes curated examples of successful API proposals with annotated lessons

Reviewed changes

Copilot reviewed 3 out of 3 changed files in this pull request and generated 1 comment.

File	Description
.github/skills/api-proposal/SKILL.md	Main skill definition with 6-phase pipeline (311 lines), including detailed instructions for prototyping, validation, and proposal drafting
.github/skills/api-proposal/references/api-proposal-checklist.md	Quality validation checklist organized by section (Background/Motivation, API Surface, Scope, Prototype, etc.)
.github/skills/api-proposal/references/proposal-examples.md	Curated examples from 6 successful proposals (#43957, #75070, #782, #60393, #1541, #36391, #74385) with annotated lessons

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[Copilot]

Pull request overview

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

[Copilot]

Pull request overview

Copilot reviewed 3 out of 3 changed files in this pull request and generated no new comments.

[tannergooding]

See #124806 for an end-to-end example of this skill producing a working prototype and proposal.

I worry about the skill opening a PR since, even if just to close it, since that is directly counter to our current guidelines on how to do API proposals (where we say no PR should be opened until its been reviewed/approved).

Can we get it to do everything and link to the branch with the prototype instead?