skills.rest
machenjie
machenjieCOMMUNITY
Explore all skills by this author →
GitHub

sdk-library-contract-design

Design SDK and library contracts to minimize breaking upgrades across semver.

4|Updated May 16, 2026
Search Tags:#semantic versioning#supply chain#api diff#sdk design#generated clients#deprecation policy#compatibility testing
One-click install
npx skills add https://github.com/machenjie/rd-skills --skill sdk-library-contract-design
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: sdk-library-contract-design
Source: https://github.com/machenjie/rd-skills/tree/main/src/foundation/capabilities/sdk-library-contract-design
Command: npx skills add https://github.com/machenjie/rd-skills --skill sdk-library-contract-design

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

It prevents breaking changes by helping you design SDKs and libraries so consumers can adopt them safely across versions, generated clients, deprecations, and migrations.

Core Features & Use Cases

It defines the contract surface (types, errors, config keys, operations, defaults, extension points), enforces semantic change classification (patch/minor/major), and prescribes reproducible client generation and compatibility verification. It is used when you add, remove, regenerate, version, publish, or migrate an SDK/library contract, including examples and documentation that must match the released artifact.

Quick Start

Use this skill to produce a complete SDK/library contract plan and release checklist for your next public or internal contract change.

Frequently Asked Questions about sdk-library-contract-design

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

FAQPage Schema
How do I design SDK contracts that survive upgrades without breaking consumer applications?▼

To design SDK contracts that survive upgrades, you must explicitly define the contract surface, enforce semantic change classification across patch, minor, and major versions, and implement compatibility tests. This ensures consumers can adopt new versions safely.

How does semantic versioning apply to removing API operations or config keys in a library?▼

Semantic versioning classifies the removal of API operations or config keys as a major breaking change. You must document a deprecation policy and provide a migration window so downstream teams can update their generated clients before upgrading.

What is the best way to verify compatibility when publishing generated client artifacts?▼

The best way to verify compatibility for generated client artifacts is to pin reproducible generation inputs and run consumer tests against the defined contract surface. This validates that semantic versioning rules are enforced before release.

How do I plan a deprecation and migration window for a reusable library framework?▼

Planning a deprecation and migration window involves documenting the removal timeline, providing replacement extension points, and ensuring rollback guarantees. This allows downstream teams to adapt their generated clients without experiencing breaking upgrades.

Does this approach work for internal plugins and generated clients used by downstream teams?▼

Yes, this approach applies to authoring and publishing contract changes for reusable libraries, frameworks, plugins, and generated client artifacts used by internal downstream teams. It requires explicit contract-surface definition and change classification.

What should be included in an SDK contract surface definition to prevent breaking changes?▼

An SDK contract surface definition must include types, errors, config keys, operations, defaults, and extension points. Defining these elements explicitly ensures that semantic versioning and compatibility testing can effectively prevent breaking upgrades.

Related Skills

Explore More Software Engineering Skills→
fjpulidopfjpulidop
9

sr-compat-check

Audit API surfaces against stored baselines and generate migration plans.

Community
Advanced
baphledbaphled
1

breaking-changes

Implement Semantic Versioning, deprecation workflows, and migration patterns for API evolution.

Community
Intermediate
proffesor-for-testingproffesor-for-testing
436

contract-testing

Verify microservice API providers against consumer-driven Pact contracts in CI/CD pipelines.

Community
Advanced
jxxghpjxxghp
11.5k

moviepilot-update

Automate restart, version checking, and upgrade workflows for MoviePilot deployments.

Community
Advanced