Agent skill · software engineering · aaronontheweb
api-design
Design stable, compatible public APIs using extend-only design principles. Manage API compatibility, wire compatibility, and versioning for NuGet packages and distributed systems.
Why this skill is useful
Provides specific guidelines for API design and versioning that the AI wouldn't reliably generate on its own.
What it needs
About 6k tokens when loaded. Last updated 2026-07-03. 1,095 stars on the source repository.
What this skill does
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 1. Previous functionality is immutable - Once released, behavior and signatures are locked 2. New functionality through new constructs - Add overloads, new types, opt-in features 3. Removal only after deprecation period - Years, not releases Benefits Old code continues working in new versions New and old pathways coexist Upgrades are non-breaking by default Users upgrade on their schedule Resources: Extend-Only Design OSS Compatibility Standards --- API Change Guidelines Safe Changes (Any Release) Unsafe Changes (Never or Major Version Only) Deprecation Pattern --- API Approval Testing Prevent accidental breaking changes with automated API surface testing. Using ApiApprover + Verify Creates ApprovePublicApi.verified.txt: Any API change fails the test - reviewer must explicitly approve changes. PR Review Process 1. PR includes changes to .verified.txt files 2. Reviewers see exact API surface changes in diff 3. Breaking changes are immediately visible 4. Conscious decision required to approve --- Wire Compatibility For distributed systems, serialized data must be readable across versions. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills aaronontheweb/csharp-api-design