csharp-api-design_skill

This skill helps you design stable public APIs and manage compatibility across versions by applying extend-only principles for .NET libraries.

Shell

643

GitHub Stars

1

Bundled Files

2 months ago

Catalog Refreshed

4 months ago

First Indexed

Readme & install

Copy the install command, review bundled files from the catalogue, and read any extended description pulled from the listing source.

Installation

Preview and clipboard use veilstrat where the catalogue uses aiagentskills.

npx veilstrat add skill aaronontheweb/dotnet-skills --skill csharp-api-design

SKILL.md9.7 KB

Overview

This skill helps .NET library authors design stable, backward- and forward-compatible public APIs using extend-only principles. It covers API/source, binary, and wire compatibility, versioning guidance, deprecation patterns, and automated API approval testing to prevent accidental breaks. Use it to make intentional, low-friction changes to NuGet packages and distributed systems.

How this skill works

The skill inspects public surface areas, serialization formats, and change plans to determine compatibility risks. It recommends safe edits (additions, optional params, new types), flags unsafe changes that must be deferred to a major release, and prescribes wire-evolution phases (read-side first, opt-in write, then default). It also integrates API approval testing using PublicApiGenerator + Verify to surface any API diffs in PRs.

When to use it

Designing a new public API for a NuGet package or shared library
Making changes to existing public types, methods, or enums
Planning schema or protocol changes for distributed systems
Reviewing pull requests that touch the public API surface
Defining a versioning or deprecation strategy for releases

Best practices

Follow extend-only design: never remove or change, only add and deprecate with notice
Use semantic versioning: breaking changes only in major releases, deprecate before remove
Protect wire compatibility: implement read-side support before enabling new writers
Run automated API approval tests to detect accidental surface changes
Mark non-public surfaces clearly (Internal namespaces or [InternalApi]) and seal classes not intended for inheritance

Example use cases

Add a new optional parameter or overload to a public method without breaking callers
Introduce a HeartbeatV2 message where readers accept both v1 and v2 while write-side remains opt-in
Enforce a PR policy that requires updating .verified.txt and documenting any intended breaking change
Deprecate a method with [Obsolete] and add an async replacement, removing only in the next major
Migrate from reflection-based serialization to schema-based formats (Protobuf, MessagePack) to improve wire stability

FAQ

Socialize the change, provide a migration path, mark the old API obsolete in a minor release, and schedule removal for a future major release.

Which serialization formats are safest for wire compatibility?

Schema-based formats (Protocol Buffers, MessagePack with contracts, System.Text.Json with source generation) are preferred; avoid reflection-based payloads like BinaryFormatter or type-name embedding.