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.
npx skills add majiayu000/claude-skill-registry --skill api-design-aaronontheweb-dotnet-skills --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# 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 ol
- When to Use This Skill
- The Three Types of Compatibility
- Extend-Only Design
- Three Pillars
- Benefits
- API Change Guidelines
- Safe Changes (Any Release)
- Unsafe Changes (Never or Major Version Only)
- Deprecation Pattern
- API Approval Testing
- Using ApiApprover + Verify
- PR Review Process
- Wire Compatibility
- Requirements
dotnet add package PublicApiGenerator dotnet add package Verify.Xunit
What does the api-design skill do?
Design stable, compatible public APIs using extend-only design principles. Manage API compatibility, wire compatibility, and versioning for NuGet packages and distributed systems.
How do I install it?
Run `npx skills add majiayu000/claude-skill-registry --skill api-design-aaronontheweb-dotnet-skills --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From majiayu000/claude-skill-registry, a repository with 534 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.