Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    Api Compatibility Checker

    1

    Api Compatibility Checker - A Premium AI Agent Skill

    $7.99

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned
    Api Compatibility Checker

    Api Compatibility Checker

    Example session with this skill installed

    Initialize a api compatibility checker config and run a workflow named my-api-compatibility-checker-workflow.

    • Read your context and instructions
    • Compiled the api compatibility checker
    • Config initialized in config/config.yaml.
    • Running api-compatibility-checker workflow: my-api-compatibility-checker-workflow...
    • Success.
    • Report: reports/api-compatibility-checker-report.md

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

    About this skill

    Api Compatibility Checker

    # API Compatibility Checker

    Shipping an API update that breaks your consumers is a trust-killer. Every time you add a field, change a response, or rename a parameter, there is a risk that existing clients will fail silently or crash outright. Manual review of API diffs is error-prone, slow, and does not scale across microservice architectures. Most teams discover breaking changes only after deployment, when customer integration tests start failing and support tickets pile up. Existing tools like oasdiff are powerful but sit outside the agent workflow. You have to switch context, run a separate CLI command, and manually interpret the diff. This skill brings breaking change detection directly into your AI agent's workflow, so you can verify compatibility during code review, before a PR merges, or as part of a CI pipeline.

    What It Does

    • Compares two OpenAPI 3.0/3.1 specs (JSON or YAML) and produces a detailed diff report
    • Classifies every change as breaking, warning, or safe/additive
    • Detects removed endpoints, removed HTTP methods, added required parameters, schema type changes, removed properties, enum value changes, constraint changes, request body changes, and response schema changes
    • Generates reports in Markdown (human-readable) or JSON (machine-readable for CI)
    • Supports --fail-on-breaking flag for CI/CD pipelines (exit code 1 if breaking changes found)
    • Includes sample specs for immediate testing

    Frameworks/Standards Covered

    | Standard/Framework | Support | |---|---| | OpenAPI 3.0.3 | Full spec comparison | | OpenAPI 3.1.0 | Full spec comparison | | JSON Schema | Deep property comparison, type checking, constraint validation | | Swagger 2.0 | Partial (YAML/JSON loading supported, but some structures differ) | | REST API Versioning | URL-based and header-based versioning patterns documented | | Semantic Versioning | Breaking change detection maps to MAJOR version bumps | | CI/CD Integration | Jenkins, GitHub Actions, GitLab CI, CircleCI |

    Detailed Feature Breakdown

    ### Endpoint Change Detection The tool identifies every path and HTTP method in both specs. It flags removed endpoints (breaking), added endpoints (safe), and modified endpoints. For modified endpoints, it drills into parameters, request bodies, and responses. ### Parameter Analysis For each operation, the tool compares all parameters across four locations: path, query, header, and cookie. It detects: - Removed parameters (breaking: existing clients will send invalid data) - Added required parameters (breaking: existing clients will fail) - Added optional parameters (safe: backward compatible) - Parameters that became required (breaking) - Parameters that became optional (safe) - Schema changes within parameters (type changes, constraint changes) ### Schema Deep Comparison The recursive schema comparator walks the full property tree of both objects. It detects: - Removed properties (breaking: clients reading those fields get undefined) - Added required fields (breaking: new responses will fail validation) - Type changes (breaking: parsers expecting string will fail on integer) - Enum value removals (breaking: exhaustive switch statements break) - Enum value additions (warning: may break exhaustive clients) - Format, pattern, min/max, minLength/maxLength, minItems/maxItems changes ### Response Body Analysis Compares every response status code and media type. Removed responses are breaking (clients expecting 200 will fail on 404). Common response schemas are compared recursively. ### Request Body Analysis Detects added/removed request bodies, required/optional transitions, and schema changes within body content types. ### CI/CD Integration The --fail-on-breaking flag causes the tool to exit with code 1 when any breaking changes are detected. This makes it suitable for use in GitHub Actions, GitLab CI, Jenkins, and other CI pipelines. The JSON output format allows programmatic parsing of results.

    Usage

    ### Quick Start ```bash # Compare two OpenAPI specs python3 scripts/cli.py samples/petstore-v1.json samples/petstore-v2.json # Generate JSON report for CI python3 scripts/cli.py samples/petstore-v1.json samples/petstore-v2.json --format json --output reports/breaking-report.json # Fail CI pipeline if breaking changes found python3 scripts/cli.py base.yaml revision.yaml --fail-on-breaking ``` ### Configuration The config/config.yaml file controls default behavior: ```yaml api_compatibility_checker: default_format: markdown # Default output format output_dir: ./reports # Default output directory fail_on_breaking: false # Exit with code 1 on breaking changes max_recursion_depth: 10 # Max schema recursion depth ```

    Output Format

    ### Markdown Report ``` # API Compatibility Report Base spec: `samples/petstore-v1.json` Revision spec: `samples/petstore-v2.json`

    Summary

    FAIL: 3 breaking change(s) detected. | Metric | Count | |---|---| | Total changes | 7 | | Breaking changes | 3 | | Warnings | 2 | | Safe changes | 2 | ``` ### JSON Report ```json { "summary": { "base_spec": "samples/petstore-v1.json", "revision_spec": "samples/petstore-v2.json", "total_changes": 7, "breaking_changes": 3, "compatible": false }, "changes": [ { "type": "endpoint_removed", "severity": "breaking", "path": "GET /pets", "detail": "Endpoint removed" } ] } ```

    Why This Beats Prompting It Yourself

    AspectAd-Hoc PromptingThis Skill Prompting an AI This Skill --- --- --- Accuracy Misses subtle breaking changes like enum removals or constraint changes Systematic recursive comparison catches everything Consistency Varies by model and context Deterministic, same results every time Schema depth Shallow comparison, misses nested type changes Full recursive comparison with $ref resolution CI integration Cannot be automated --fail-on-breaking flag for CI pipelines Speed Takes multiple prompt rounds Single command, instant results Documentation No report generation Markdown and JSON reports Reproducibility Depends on model state Fully deterministic

    Use Cases

    • CI/CD Pipeline Gate: Run the compatibility checker as a GitHub Action step before every API deployment. Block the build if breaking changes are detected without explicit approval.
    • Pull Request Review: Automatically compare the proposed OpenAPI spec against the current production spec. Post a compatibility report as a PR comment so reviewers can see exactly what changed.
    • API Version Planning: Before creating a new API version, diff the proposed spec against the current version. Use the output to write accurate migration guides and deprecation notices.
    • Third-Party API Monitoring: Periodically compare known third-party API specs against newly fetched versions. Detect when a dependency's API has changed in ways that will break your integration.
    • Microservice Contract Verification: In a microservice architecture, each service publishes its OpenAPI spec. Run the checker across service boundaries to verify that consumer-driven contracts are still satisfied.

    1. Manual review still recommended for production.
    2. Large workloads may need tuning.
    3. Very long sessions may lose state.

    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 any payment.

    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 4 months ago

    Permissions

    Terminal / Shell
    Write Files
    Listed4 months ago

    What's inside

    Frequently Asked Questions

    The Api Compatibility Checker skill is a premium AI agent skill that provides a complete solution for api compatibility checker workflows.

    Install the skill, run the init command, and refer to the Quick Start section.

    Claude Code, Cursor, GitHub Copilot, and SKILL.md-compatible agents.

    The skill addresses: Missing $ref resolution for external files: The tool only resolves internal $ref references (pointing to components/schemas). External file references (e.g., ./schemas/common.yaml) will not be resolved. Mitigation: Merge external refs into a single spec file before running the comparison. (mitigation: Follow recommended guidelines.); Circular $ref references: Deeply nested schemas with circular references (e.g., a Category containing a list of Products that each have a Category) can cause infinite recursion. The tool has a max_recursion_depth of 10 to prevent stack overflow, but circular refs will stop comparison early. Mitigation: Set a higher depth limit in config, or flatten circular schemas before comparison. (mitigation: Follow recommended guidelines.); allOf/oneOf/anyOf composition: The tool does not fully resolve JSON Schema composition keywords. It compares properties directly, but does not expand allOf, oneOf, or anyOf combinators. Mitigation: Pre-process specs with a JSON Schema dereferencer before running the tool. (mitigation: Follow recommended guidelines.).

    Standardized templates, repeatable CLI commands, comprehensive checks, and full reports vs. inconsistent ad-hoc results.

    Yes. The CLI can be invoked from any CI/CD runner, and configs can be version-controlled.

    One-time purchase. No recurring fees.

    New in Testing & Debugging