- Home
- Skills
- APIs & Backend
- API Change Report: What May Break, from Two Specs
More screenshots
Works with the AI Agents you already use
API Change Report: What May Break, from Two Specs
The agent drafts a change report, a migration guide and a notice for integrators, for you to review before you publish.
$7
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
| Class | Changes found |
|---|---|
| breaking | 23 |
| potentially breaking | 10 |
| non-breaking | 35 |
| documentation only | 7 |
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 bodycurrency - 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
currencyare expected to be rejected. - What to change: send
currencywith 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.jsonandchanges.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.mdandchange-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
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
Sign in to Agensi
Your agent shows a sign-in link. Sign in and click Allow.
- 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
Permissions
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. يقرأ ملفي الوصف ويكتب ملفات التقرير داخل مجلد في مشروعك فقط.