Api Design

Aaron Stannard built this for .NET developers who need to think carefully about public API surface area and versioning. It walks you through the three types of compatibility (binary, source, and wire format) and helps you catch breaking changes before they ship to NuGet. The skill shines during PR reviews and when you're planning migrations for distributed systems where wire format matters. It's opinionated in a good way, the kind of guidance that comes from shipping real libraries and dealing with the consequences of bad breaking changes. If you maintain anything with external consumers, this will save you from angry GitHub issues six months down the line.

skills.sh installs: 690
GitHub stars: 1.3K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add aaronontheweb/dotnet-skills --skill api-design --agent claude-code

Installs into .claude/skills of the current project.

Files

Public API Design and Compatibility

When to Use This Skill

Use this skill when:

Designing public APIs for NuGet packages or libraries
Making changes to existing public APIs
Planning wire format changes for distributed systems
Implementing versioning strategies
Reviewing pull requests for breaking changes

The Three Types of Compatibility

Type	Definition	Scope
API/Source	Code compiles against newer version	Public method signatures, types
Binary	Compiled code runs against newer version	Assembly layout, method tokens
Wire	Serialized data readable by other versions	Network protocols, persistence formats

Breaking any of these creates upgrade friction for users.

Extend-Only Design

The foundation of stable APIs: never remove or modify, only extend.

Three Pillars

Previous functionality is immutable - Once released, behavior and signatures are locked
New functionality through new constructs - Add overloads, new types, opt-in features
Removal only after deprecation period - Years, not releases