skills.rest
erraggy
erraggyCOMMUNITY
Explore all skills by this author →
Website𝕏@erraggyGitHub

diff-specs

Diff two OpenAPI specifications to identify breaking changes and migration steps.

5|5|Updated Nov 9, 2025
Search Tags:#versioning#openapi#migration#diff#breaking-changes#api-diff-tool
One-click install
npx skills add https://github.com/erraggy/oastools --skill diff-specs
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: diff-specs
Source: https://github.com/erraggy/oastools/tree/main/plugin/skills/diff-specs
Command: npx skills add https://github.com/erraggy/oastools --skill diff-specs

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

Diff two OpenAPI specifications to identify breaking changes, categorize them by severity, and propose migration steps.

Core Features & Use Cases

  • Surface breaking changes between two API versions
  • Categorize changes by severity and generate migration guidance
  • Produce structured outputs to guide API evolution and client updates

Quick Start

Run the diff tool with the old version and the new version to generate a categorized changes report.

Frequently Asked Questions about diff-specs

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

FAQPage Schema
How do I find breaking changes between two OpenAPI specification versions?▼

To find breaking changes between two OpenAPI specification versions, you diff the old and new specs to surface modifications, categorize them by severity, and generate structured migration guidance for client updates.

What is the best way to categorize API breaking changes for migration planning?▼

Categorizing API breaking changes for migration planning involves diffing OpenAPI versions to identify severity levels, which produces structured outputs that guide API evolution and detail necessary client remediation steps.

How do I generate migration steps after updating an OpenAPI specification?▼

You generate migration steps after updating an OpenAPI specification by running a diff against the previous version, allowing the tool to identify breaking changes and propose structured remediation guidance for the transition.

Can I compare two OpenAPI specs to identify which API endpoints have breaking changes?▼

Yes, you can compare two OpenAPI specs to identify breaking changes by diffing the different versions of the same API, which surfaces and categorizes the specific modifications that require client updates.

Does the OpenAPI diff tool support paginated results for large specification files?▼

Yes, the OpenAPI diff tool supports paginated results, enabling you to systematically review categorized breaking changes and migration guidance when handling large specification files.

When do I need to diff OpenAPI specifications for breaking changes?▼

You need to diff OpenAPI specifications for breaking changes when comparing different versions of the same API, ensuring you surface any modifications that could impact existing clients and require structured migration steps.

Related Skills

Explore More Software Engineering Skills→
teexiiiteexiii

swagger

Serve interactive Swagger UI and raw OpenAPI spec from a TypeScript-based definition.

Community
Intermediate
mouayadakelmouayadakel

api-contract

Validate API contract changes for breaking modifications and client impact.

Community
Intermediate
smartsheetsmartsheet
21

implement-api-endpoint

Implement Smartsheet JavaScript SDK API endpoints with OpenAPI compliance and TypeScript tests.

Official
Advanced
rafaelromaorafaelromao
5

sandman-self-review

Review code changes against coding standards and specification adherence.

Community
Advanced