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

review-public-api

Reviews proposed ASP.NET Core public APIs against repo conventions and recommends shape changes.

1.2k|337|Updated Oct 13, 2022
Search Tags:#API Design#public api#aspnet core#Code review#API review#DotNet#ref assembly
One-click install
npx skills add https://github.com/dotnet/dotnet --skill review-public-api
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: review-public-api
Source: https://github.com/dotnet/dotnet/tree/main/src/aspnetcore/.github/skills/review-public-api
Command: npx skills add https://github.com/dotnet/dotnet --skill review-public-api

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

Reviewing a proposed public API for dotnet/aspnetcore requires deep knowledge of the @dotnet/aspnet-api-review team's unwritten conventions, and inconsistent reviews lead to permanent, hard-to-change public surface mistakes.

Core Features & Use Cases

  • Need Assessment: Judges whether an API should exist at all by modeling real-world scenarios, commonality (happy-path vs edge-case), and target audience (end-app-developer vs library-author).
  • Convention Enforcement: Applies ASP.NET Core-specific rules on naming, async/CancellationToken, nullability, return types, sealing, overloads, type placement, and breaking changes.
  • Structured Output: Produces a verdict, per-type bullet changes with grounded reasoning, and a ref-assembly diff against the current repo API surface.
  • Use Case: Given an api-ready-for-review issue proposing a new endpoint helper, the Skill evaluates whether it belongs in the framework, flags a missing CancellationToken and an unsealed class, and emits a diff showing the recommended signature.

Quick Start

Ask the AI to review this ASP.NET Core API proposal and recommend changes to its public shape.

Frequently Asked Questions about review-public-api

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

FAQPage Schema
How do I review a public API proposal for ASP.NET Core?▼

Read the proposal as a ref-assembly diff, assess whether the API should exist using commonality and target-audience framing, then apply the repo's conventions on naming, async, nullability, and sealing. Emit a verdict, per-type changes with grounded reasoning, and a diff against the current API surface.

What conventions does the ASP.NET Core API review team apply?▼

Key conventions include sealing types by default, adding CancellationToken as the last parameter on async methods, returning IReadOnlyList for read-only collections, avoiding public records, and following Add/Use/Map/With method family contracts. Smaller public surface and consistency with existing APIs win when rules conflict.

When should an API proposal be declined in review?▼

Decline when there is no demonstrated demand, when the API is achievable as a user extension method, when it changes a shipped default, or when it encourages an anti-pattern or pollutes HttpContext IntelliSense. Even when declining, provide the need assessment and point to an existing mechanism or workaround.

Does this skill implement or build the proposed API?▼

No, it only reviews the proposed API shape and recommends changes. It explicitly does not implement approved APIs, write analyzers, run builds, or perform general code review unrelated to the public API surface.

What output format does an ASP.NET Core API review produce?▼

The output is a verdict (looks good, changes recommended, or recommend not adding), a need assessment with scenario modeling, and per-type bullet changes with a Why paragraph plus a ref-assembly style diff comparing existing and recommended signatures.

Related Skills

Explore More Software Engineering Skills→
dotnetdotnet
18.2k

api-proposal

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

Official
Advanced
MagicBowenMagicBowen
4

dogent-story-implementation

Automate Dogent story implementation, unit tests, and sprint doc updates.

Community
Advanced
ojrojasojrojas

migrate-dotnet8-to-dotnet9

Migrate .NET 8 projects to .NET 9 with breaking change resolution.

Community
Advanced
lewinglewing

dotnet-inspect

Inspect .NET library APIs across NuGet packages, platform libraries, and local DLLs.

Community
Intermediate