More screenshots

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIDeepSeekDeepSeekMuseMuse+22 more

    OpenAPI Breaking Changes: Diff two specs before release

    1

    Don't learn about a breaking change from your API consumers. Diff two OpenAPI 3 JSON specs and list every break: removed endpoints, new required fields, narrowed enums and changed responses.

    $15

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned

    OpenAPI Breaking Changes: Diff two specs before release

    Example session with this skill installed

    Compare references/baseline.json with references/breaking.json, produce Markdown, and explain the highest-priority consumer fixes without waiving rules.

    • Read your context and instructions
    • Compiled the openapi breaking changes

    OpenAPI compatibility report

    11 breaking; 2 non-breaking; 11 gated.

    • BREAKING: GET /items | query/filter | parameter_removed | removed or renamed parameter
    • BREAKING: GET /items | query/region | parameter_added | new parameter
    • NON-BREAKING: GET /items | query/search | parameter_added | new parameter
    • BREAKING: GET /items | responses/404 | status_removed | response status removed
    • BREAKING: GET /items | responses/200/application/json.id | property_removed | response property removed
    • BREAKING: GET /items | responses/200/application/json.state | enum_changed | enum ['open'] -> ['open', 'archived'] (response)
    • BREAKING: GET /items | security | auth_changed | security alternatives/scopes changed
    • BREAKING: POST /items | query/filter | parameter_removed | removed or renamed parameter
    • BREAKING: POST /items | query/region | parameter_added | new parameter
    • NON-BREAKING: POST /items | query/search | parameter_added | new parameter
    • BREAKING: POST /items | requestBody/application/json.name | required_property_added | request property now required
    • BREAKING: POST /items | requestBody/application/json.name | nullable_changed | nullable True -> False (request)
    • BREAKING: * /legacy | /legacy | path_removed | path and its operations removed

    Supported structural rules only; see references/rules.md for unchecked behavior.

    Release gated (exit 1): 11 breaking, 2 non-breaking, 0 waived. Restore the old filter and legacy route, avoid a newly mandatory region, and preserve response id/404 guarantees. Then coordinate authentication, archived response states, and required non-null request name with consumers. If these changes are intentional, publish them as a parallel version. Bumping the version number alone doesn't protect existing callers.

    Connects securely to your tools. The creator never sees your data.

    About this skill

    The problem You changed an OpenAPI spec and want to ship it as a patch. A renamed query parameter or a field that's now required looks harmless in the diff, but every client still sending the old request will break. You want to know that before you pick a version number, not after a consumer files a bug.

    See it before you buy: real input, real output Command (from the package folder, exit code 1, 0.023 s):

    python3 -I -B scripts/openapi_diff.py references/baseline.json references/breaking.json --format markdown
    

    Before: Two versions of the same API contract: baseline.json and breaking.json (OpenAPI 3.1, JSON).

    After: lines copied from the script's output (excerpt):

    11 breaking; 2 non-breaking; 11 gated.
    - BREAKING: GET /items | query/filter | parameter_removed | removed or renamed parameter
    - BREAKING: GET /items | responses/404 | status_removed | response status removed
    - BREAKING: POST /items | query/filter | parameter_removed | removed or renamed parameter
    - BREAKING: * /legacy | /legacy | path_removed | path and its operations removed
    

    What the numbers show

    • Ran on two real releases of the public Swagger Petstore spec (1.0.3 and 1.0.29, 19 operations each): 8 breaking and 32 non-breaking changes.
    • I checked all 8 breaks and 2 of the additions by hand against both spec versions: all 10 were real.
    • Honest limit: this shows the reported findings are right, not how many changes it misses. The Petstore run printed 5 warnings about things it doesn't compare.

    What you get

    • A Python script that compares the released spec with your new one. It has 19 rules covering paths, operations, parameters, request and response fields, media types, status codes and auth requirements.
    • Instructions that tell the agent to run it, explain what each break means for callers, and list fixes in priority order.
    • A JSON report for CI and a Markdown report for pull request review. Both list each finding with its endpoint and location.
    • Exit codes you can gate on: 0 means no unaccepted breaks, 1 means at least one break is blocking, 2 means the input couldn't be read.
    • --allow-breaking-for to accept a whole rule (say, removed status codes) when you mean it. Accepted breaks still show in the report.
    • Example specs, rule notes, 26 test cases and 4 saved sample reports you can check against a fresh run.

    Measured on real data (full detail) I ran it on two real releases of the public Swagger Petstore spec, 1.0.3 and 1.0.29. Each has 13 paths and 19 operations. The originals are YAML, so I converted them to JSON and inlined their internal references first. The script only reads JSON.

    ComparisonBreakingNon-breakingBlocking the releaseTypical run time
    Petstore 1.0.3 → 1.0.2983280.03 s
    Included breaking example112110.03 s
    Included compatible example0300.03 s

    I checked all 8 Petstore breaks and 2 of the additions by hand against both spec versions. All 10 were real and matched the documented rule. That tells you the reported findings are right. It doesn't tell you how many changes the script misses. The Petstore run also printed 5 warnings about things it doesn't compare, like formats and additionalProperties, so you'd review those yourself. Run time is the median of 5 runs including Python startup, on an ordinary Linux machine. The conversion steps, file hashes and exact commands are in references/benchmarks.md.

    Known limitations

    • Accepts OpenAPI 3.0/3.1 JSON only. Convert YAML separately with a trusted tool.
    • Rejects external references, cycles, and assertion siblings beside references, even in unused components.
    • Doesn't fully compare composition, constraints, headers, serialization, or runtime behavior. Review warnings and run consumer tests.
    • Treats type changes as breaking. Added response statuses and media types are non-breaking by policy, which may not suit clients that reject unexpected values.
    • Waivers apply to a whole rule across the comparison. Exit 0 doesn't prove consumer compatibility.

    Who it's for API maintainers reviewing pull requests and release owners who need to explain contract changes to consumers.

    Requires Python 3.8+, two UTF-8 OpenAPI 3.0.x/3.1.x JSON files, and an agent host that can read text and run Python. The script uses the standard library and needs no installed packages. The benchmark's YAML converter isn't included or needed for JSON inputs.

    Privacy: runs locally, no network, no telemetry, and writes nothing unless you redirect output.

    Check it yourself 26 test cases and 4 saved sample outputs were checked against fresh runs. From the package folder, run python3 -I -B scripts/openapi_diff.py references/baseline.json references/breaking.json --format markdown to reproduce the demo, which exits 1 with 11 breaking findings. Use references/compatible.json as the candidate for exit 0 with 3 non-breaking changes. See references/benchmarks.md to rerun all cases and reproduce the prepared public comparison.

    Price and guarantee $15 one time, yours to use with any agent that can run Python. Covered by Agensi's money-back guarantee if it doesn't do what this page promises.

    Find more skills like this on the Claude Skills Marketplace, the Codex Skills Marketplace and the Gemini Skills Marketplace, or browse Claude Skills for APIs & Backend.

    No YAML or OpenAPI 2.0 support. Ignores webhooks, headers, and validation constraints. Requires Python 3.8+. Limited to 100,000 nodes or 100 reference hops.

    How to use

    1. 1

      Connect your agent to the Agensi MCP

      Copy the prompt and paste it into Claude, ChatGPT, Cursor or any agent that supports MCP. It sets up the connection for you. Manual setup

    2. 2

      Sign in to Agensi

      Your agent shows a sign-in link. Sign in and click Allow.

    3. 3

      Ask for what you need

      Your agent loads this skill and uses it on your task. It always asks before buying a skill.

    Reviews

    No reviews yet

    Be one of the first to try it. Every listed skill goes through the trust checks below.

    Security scanned

    Checked by our 8-point scan before listing

    Fresh listing

    Recently published to Agensi

    Money-back guarantee

    Doesn't do what its page promises? You get your money back.

    Trust & safety

    Security scan

    Security scan passed 15 days ago

    Software
    Python 3

    Permissions

    Terminal / Shell
    Read Files
    Write Files

    Uses the host's terminal to invoke Python and file-read access for the two user-supplied specifications. The script reads only those inputs, prints stdout/stderr, and writes no files. Optional shell redirection saves output at the user's chosen path. No network access, no telemetry, and nothing is sent anywhere.

    Listed15 days ago
    Updated5 days ago

    What's inside

    Frequently Asked Questions

    If you can install them, they're good tools and cover more of the spec than this does. This is for when you want a single Python file with no dependencies and an agent that explains each break and what to do about it.

    It means no unwaived breaks were found under the supported rules. Review warnings, unchecked behavior, and consumer tests before making that decision.

    Convert both files to JSON with a trusted tool first. The script rejects YAML and installs nothing.

    Agensi's money-back guarantee covers every paid skill: if it doesn't do what this page promises, you get your money back. Everything above is output from the script in the package, so you can see what it does before you buy.

    New in APIs & Backend