More screenshots

    Works with the AI Agents you already use

    Claude CodeClaude CodeCursorCursorCodex CLICodex CLIMuseMuseDotsDots+21 more

    API Change Report: What May Break, from Two Specs

    1

    The agent drafts a change report, a migration guide and a notice for integrators, for you to review before you publish.

    $7

    Secure checkout via Stripe

    Money-back guarantee

    Converts to your local currency at checkout

    Security scanned
    API Change Report: What May Break, from Two Specs

    API Change Report: What May Break, from Two Specs

    Example session with this skill installed

    We are cutting v2 of the orders API next sprint. openapi-v1.yaml is what is live and openapi-v2.yaml is the v2 branch. I need what actually breaks for integrators, a migration guide, a changelog entry and a short email to merchant developers.

    • Read your context and instructions
    • Compiled the api change report

    Summary

    ClassChanges found
    breaking23
    potentially breaking10
    non-breaking35
    documentation only7

    After grouping repeated and related rows: 11 breaking entries, 4 potentially breaking entries.

    3. currency is required when creating an order

    • Where: POST /orders, request body currency
    • What changed: new required property, type string, pattern ^[A-Z]{3}$. The old body had no currency.
    • What you will see: create-order requests without currency are expected to be rejected.
    • What to change: send currency with every create-order request.

    Step 1. Point the client at the v2 base URL

    Old version availability: [NEEDS: date the v1 URL stops working]

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

    About this skill

    English

    For backend developers, API teams and agencies who ship a new version of an HTTP API and have to tell the people who call it what changed.

    Give your agent the old and the new description of your API (OpenAPI 3.x or Swagger 2.0, JSON or YAML). The agent drafts a change report, a migration guide and a notice for integrators, for you to review before you publish.

    The report lists potentially breaking changes found by comparing the two files. It is a starting point for your team's review, not a confirmed compatibility assessment.

    A bundled script compares the two files and classifies every difference by fixed rules. The agent then writes what each change means for a client: what it will see, and what it has to change.

    What the agent writes each run

    • changes.json and changes.csv: every difference with an id, a class (breaking, potentially breaking, non-breaking, documentation only), its kind, the method and path, and the old and new value.
    • change-report.md and change-report.html: the summary counts, then breaking changes first, each with where it is, what changed, what a client will see and what to change. The HTML is one printable page with no outside files.
    • migration-guide.md: steps for the developers who call the API, with before and after snippets taken from the two files.
    • changelog-entry.md: a changelog entry and a suggested version bump with the reasoning. The team decides.
    • consumer-notice.md: a short, factual announcement for integrators.
    • notes.md: what was compared, what a comparison of two files cannot show, and what needs a decision.

    Rules, not guesses

    The script knows 118 kinds of change in four classes, with separate rules for what a client sends and what it receives: a new required request field is breaking, a new response field is not. It follows local $refs. Run api_diff.py rules to read every rule. check then confirms that every breaking id is covered in the report and in the guide.

    Your facts only

    The skill instructs the agent to take snippets, paths and values from your two files, and to mark what you did not supply, such as a shutdown date for the old version, as [NEEDS: ...] instead of filling it in.

    Honest about its limits

    It compares two files. It does not call your API, so behaviour that the description does not state is outside its view. Classes come from rules and are for your team to confirm. Only local $refs are followed: a spec split over several files gives a warning and an incomplete comparison. The YAML reader covers the common subset and names the line when it meets something else (convert that file to JSON). Regex patterns and oneOf / anyOf are reported as changed without being evaluated. Response headers, links, callbacks and webhooks are not compared. With no spec the agent can compare a simple endpoint list it builds from your route files; that path is weaker and was not run end to end in testing. The HTML page was checked by reading its source, not in a browser.

    Arabic

    On request the report, the guide and the notice are written in Arabic and the HTML page is set right to left, with paths and JSON kept left to right.

    In the download: SKILL.md, four standard-library Python scripts, references (the rules, how to write each entry, input formats, Arabic notes), templates, and a worked example you can read before you buy: a payments API going from 1.8.0 to 2.0.0, with 75 differences grouped into 11 breaking entries.

    Tried on two cases (an OpenAPI 3 YAML payments API in English; a Swagger 2.0 JSON clinic API with an Arabic report). The scripts have 85 unit tests.

    بالعربي

    لمطوّري الواجهات الخلفية وفرق الـ API الذين يصدرون نسخة جديدة ويحتاجون أن يخبروا مستخدميها بما تغيّر.

    أعطِ وكيلك ملف وصف النسخة القديمة وملف النسخة الجديدة (OpenAPI 3 أو Swagger 2، بصيغة JSON أو YAML). يكتب لك مسودة تقرير التغييرات ودليل الترحيل وإشعارًا للمطوّرين، لتراجعها قبل النشر.

    ماذا يكتب الوكيل

    • ملفا changes.json وchanges.csv: كل فرق مع رقمه وتصنيفه ومكانه والقيمة القديمة والجديدة.
    • ملف change-report: التغييرات الكاسرة أولًا، ومع كل تغيير ما الذي سيراه العميل وما الذي عليه تعديله.
    • ملف migration-guide.md: خطوات الترحيل مع مقاطع قبل وبعد مأخوذة من ملفيك.
    • ملف changelog-entry.md وملف consumer-notice.md: سجل التغييرات وإشعار قصير.

    حدودها

    النتائج تغييرات يُحتمل أن تكون كاسرة وتحتاج مراجعة فريقك. المهارة تقارن ملفين ولا تتصل بالـ API، فما لا يذكره الوصف لا تراه. التصنيف مبني على قواعد ثابتة ويؤكده فريقك. وتتبع المراجع داخل الملف نفسه فقط. ويمكن طلب التقرير بالعربية مع صفحة من اليمين إلى اليسار؛ جُرّب ذلك على حالة اختبار واحدة.

    It compares two description files and does not call the API, so behaviour the description does not state is outside its view. Classes are assigned by fixed rules and are for the team to confirm. Only local $ref references are followed; a spec split over several files gives a warning and an incomplete comparison. The YAML reader covers the common subset (no anchors, no multi-line quoted strings) and names the line when it stops; convert such a file to JSON. Regex patterns and oneOf / anyOf are reported as changed without being evaluated. Response headers, links, callbacks, webhooks, discriminators and examples are not compared. The script stops at a type change, so the agent reads limits such as minimum from the two schemas. The rename rule is a heuristic covered by a unit test only. The endpoint-list path for projects with no spec was not run end to end. The HTML page, including the Arabic right-to-left one, was checked by reading its source, not in a browser. Tried on two cases. التصنيف مبني على قواعد ويؤكده فريقك.

    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 2 days ago

    Requires

    python3 (3.9 or newer)
    Git

    Permissions

    Terminal / Shell
    Read Files
    Write Files

    Reads the two API description files (and route files only when you have no spec). Writes changes.json, changes.csv, change-report.md, change-report.html, migration-guide.md, changelog-entry.md, consumer-notice.md and notes.md into a folder in your project (api-change-report by default). Runs its bundled Python scripts locally; they use the standard library only, make no network calls and never call your API. يقرأ ملفي الوصف ويكتب ملفات التقرير داخل مجلد في مشروعك فقط.

    Listed2 days ago

    What's inside

    Frequently Asked Questions

    OpenAPI 3.x and Swagger 2.0, in JSON or YAML. The YAML reader covers the common subset and names the line if it meets a feature it does not read; convert that file to JSON. يقرأ OpenAPI 3 و Swagger 2 بصيغة JSON أو YAML.

    No. It compares two files on your disk. Behaviour that the description does not state is outside its view. لا، يقارن ملفين فقط.

    By fixed rules you can read with the rules command: 118 kinds of change in four classes, with separate rules for what a client sends and what it receives. Your team confirms the classes. بقواعد ثابتة تستطيع قراءتها.

    Only references inside the same file are followed. Bundle the spec into one file first; otherwise you get a warning and an incomplete comparison. ادمج الملفات في ملف واحد أولًا.

    The skill instructs the agent not to. Dates and timelines you did not supply are marked [NEEDS: ...] for you to fill in. لا، يضع علامة لتكملها أنت.

    Yes, as an added option, with a right-to-left HTML page and paths kept left to right. It was tried on one test case; read it before publishing. نعم، مع صفحة من اليمين إلى اليسار.

    New in APIs & Backend