skills.rest
dotnet
dotnetOFFICIAL
Explore all skills by this author →
Website𝕏@dotnetfdnGitHub

api-proposal

Create prototype-backed API proposals for dotnet/runtime through research, prototyping, and publishing phases.

18.2k|5.6k|Updated Sep 24, 2019
Search Tags:#csharp#prototype#gitHub#API review#DotNet#reference assembly#api proposal
One-click install
npx skills add https://github.com/dotnet/runtime --skill api-proposal
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-proposal
Source: https://github.com/dotnet/runtime/tree/main/.github/skills/api-proposal
Command: npx skills add https://github.com/dotnet/runtime --skill api-proposal

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Drafting API proposals for dotnet/runtime that survive the live API review process is hard: speculative proposals without working prototypes get sent back, and reviewers reject verbose, ungrounded submissions. This Skill guides the full pipeline from a vague API idea to a published, evidence-backed proposal.

Core Features & Use Cases

  • Prototype-first workflow: Builds and validates a working prototype (build, tests, TFM compatibility, reference assembly generation) before writing any proposal text, so the exact API surface comes from real ref source output.
  • Structured six-phase pipeline: Covers input gathering, research against Framework Design Guidelines, prototyping with adoption-site cataloging, mandatory code review, terse proposal drafting, and publishing via GitHub CLI.
  • Quality guardrails: Ships a checklist and curated examples of successful proposals (PriorityQueue, snake_case policies, async ZipFile APIs) to avoid common failure modes like invented scenarios and raw ref dumps.
  • Use Case: Given an underdeveloped api-suggestion issue, refine it into a complete proposal with a single-commit prototype branch, an adoption catalog of dotnet/runtime call sites, and a published issue ready for API review.

Quick Start

Ask the agent to draft an API proposal for your new dotnet/runtime API idea and have it prototype, validate, and publish the proposal.

Frequently Asked Questions about api-proposal

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I write an API proposal for dotnet/runtime?▼

Start with a working prototype on a single-commit branch, then extract the exact API surface using GenerateReferenceAssemblySource. Draft a terse proposal covering motivation, API surface, usage examples, alternatives, risks, and adoption sites, then publish it as an api-suggestion issue.

Why do dotnet/runtime API proposals get marked api-needs-work?▼

Proposals get sent back for unsubstantiated motivation claims, missing prototypes, overly verbose text, narrow scope that ignores neighboring APIs, and naming that violates Framework Design Guidelines. Grounding every claim in a tested prototype and real usage evidence avoids most rejections.

Does an API proposal require a working prototype?▼

Yes, the workflow treats the prototype as mandatory evidence. It must build for all target frameworks, pass all tests, maintain netstandard/netfx superset compatibility, and include committed reference assembly changes before the proposal is drafted.

How do I generate the exact API surface for a proposal?▼

Run dotnet msbuild /t:GenerateReferenceAssemblySource in the library's src directory. The resulting ref folder diff is the exact public API surface to paste into the proposal, and it must be committed with the prototype.

When should I not use this API proposal workflow?▼

Do not use it for bug fixes, code reviews, performance benchmarking, or internal API changes that do not affect the public surface area. It is designed only for proposals that add or modify public APIs in dotnet/runtime libraries.

Related Skills

Explore More Software Engineering Skills→
lalulalilalulali
8

explore-idea

Synthesize a concept brief and coordinate market, competitor, and user research.

Community
Advanced
dimakisdimakis

land-pr

Shepherd GitHub pull requests through CI checks, reviews, and squash merges.

Community
Intermediate
JennyfirrrJennyfirrr

perf-audit

Audit hot-path code changes against a declared performance budget.

Community
Advanced
kevinxo328kevinxo328
5

openspec-explore

Explore codebases and ideas to map architecture and surface risks.

Community
Intermediate