Ready to supercharge your AI agents?

Install any skill in seconds. Free to start, no credit card required.

Get Started Free →

API Compatibility Analyzer Skill · a5c-ai | DecimalAI

a5c-ai/api-compatibility-analyzer

SkillScore50Maintained

Analyze API changes for backward compatibility with breaking change detection and consumer impact assessment

Code Reviewby a5c-ai

Links this skill to your agents and keeps it current with the author’s updates.

Automatic

Coding pack

1 · One-time — install the CLI (docs ↗)

pip install decimalai

2 · Get the skill — writes .claude/skills/a5c-ai-api-compatibility-analyzer/SKILL.md

decimalai skills pull a5c-ai-api-compatibility-analyzer --out .claude/skills/

No CLI? Get the same file — curl · raw file

curl -fsSL --create-dirs -o .claude/skills/a5c-ai-api-compatibility-analyzer/SKILL.md https://app.decimal.ai/s/a5c-ai-api-compatibility-analyzer/SKILL.md

Raw file: /s/a5c-ai-api-compatibility-analyzer/SKILL.md ↗ · machine-readable summary at /s/a5c-ai-api-compatibility-analyzer.json ↗

In productionGlobal

how this skill behaves on real traffic · last 30 days

No production data for this skill yet — usage numbers appear here once agents start running it.

Anonymized aggregate across every org using this skill — proof from real production use, not a demo.

Does this skill help? · Benchmark: with vs. withoutsign in to run this on your agents

22 test cases from the publisher’s eval.yaml · each run twice on gemini-3.6-flash — with the skill injected, then without · last run 58d ago

Yes — +45% lift+19% tokens0% turns50% of whole cases pass with skill (11/22)

Test case	Without → With	Effect	Δ tokens	Δ turns
case-02	✗→✓	▲ Improved	-10%	0%
case-03	✗→✓	▲ Improved	15%	0%
case-07	✗→✓	▲ Improved	-39%	0%
case-08	✗→✓	▲ Improved	17%	0%
case-11	✗→✓	▲ Improved	-19%	0%

Showing 5 of 22 cases

SkillSafety

✓ 3 of 3 passed

Code scan15 of 15 checks clean

0 critical · 0 warning · 0 info — scanner v4 — 7/31/2026

live_secretremote_code_executionreverse_shelldata_exfiltrationssrf_metadataagent_snoopinganti_refusaldestructive_commandsobfuscated_unicodeunicode_homoglyphopaque_blobsuspicious_urltool_overreachtrigger_abuseprompt_injection_phrasing

IntentSafe

LLM judge · does the skill do what it claims

ContentClean

LLM judge · policy & harmful-content review

Source

Imported

a5c-ai / babysitter

library/specializations/code-migration-modernization/skills/api-compatibility-analyzer/SKILL.md

View on GitHub ↗

License MITImported 7/31/2026Version v1

Skill contents

SKILL.md

API Compatibility Analyzer Skill

Analyzes API changes between versions to detect breaking changes, assess consumer impact, and suggest migration strategies.

Purpose

Enable API versioning management for:

Breaking change detection
Deprecation analysis
Version comparison
Consumer impact assessment
Migration path suggestion

Capabilities

1. Breaking Change Detection

Detect removed endpoints
Identify removed fields
Find type changes
Flag required field additions

2. Deprecation Analysis

Track deprecated endpoints
Monitor deprecation timelines
Identify usage of deprecated APIs
Plan sunset schedules

3. Version Comparison

Compare OpenAPI specs
Generate detailed diffs
Categorize changes
Document migrations

4. Consumer Impact Assessment

Map affected consumers
Estimate migration effort
Identify high-impact changes
Prioritize notifications

5. Migration Path Suggestion

Recommend upgrade steps
Suggest compatibility layers
Propose versioning strategies
Design adapter patterns

6. Compatibility Layer Design

Design facade endpoints
Plan response translation
Handle version negotiation
Implement fallbacks

Tool Integrations

| Tool | Purpose | Integration Method | |------|---------|-------------------| | OpenAPI-diff | Spec comparison | CLI | | Optic | API change detection | CLI | | Akita | Traffic-based detection | API | | swagger-diff | Swagger comparison | CLI | | Spectral | API linting | CLI |

Output Schema

json
{
  "analysisId": "string",
  "timestamp": "ISO8601",
  "versions": {
    "base": "string",
    "target": "string"
  },
  "changes": {
    "breaking": [
      {
        "type": "string",
        "path": "string",
        "description": "string",
        "migration": "string"
      }
    ],
    "nonBreaking": [],
    "deprecations": []
  },
  "impact": {
    "consumers": [],
    "severity": "string",
    "migrationEffort": "string"
  },
  "recommendations": []
}

Integration with Migration Processes

api-modernization: Compatibility verification
framework-upgrade: API impact analysis

Related Skills

api-inventory-scanner: Endpoint discovery
openapi-generator: Spec generation

Related Agents

api-modernization-architect: Versioning strategy

Illustrative Want to see what a5c-ai/api-compatibility-analyzer would put in front of your model? Preview the rendered body and check its trigger phrases — no LLM call, no signup.

Latest benchmark · publisher runVerified

8/1/2026, 01:34 UTC · 22 cases

Lift

+45%

50% vs 5%

Agent turns

0%

1.0 vs 1.0

Tokens

+19%

2,627.23 vs 2,203.82

fail → pass · 10pass → pass · 1fail → fail · 11

Per-case results (22)

Case	Status	Duration (ms)			Turns			Tokens			Tool calls
Case	Status	Without	With	Δ	Without	With	Δ	Without	With	Δ	Without	With	Δ
case-01 We are updating our backend service from v1.2 to v2.0 OpenAPI specs. Please analyze the two spec versions to identify all breaking or non-breaking API modifications, along with any deprecations. We need a structured breakdown showing the base and target versions, categorized changes with migration descriptions, an impact assessment detailing affected consumers and severity/effort levels, and actionable migration recommendations.	fail→fail	18,031	24,523	+36%	1	1	0%	3,341	5,618	+68%	0	0	—
case-02 I need a comprehensive API compatibility check between our current staging definition (`/specs/v1-legacy.json`) and the proposed release candidate (`/specs/v2-rc.json`). Output a complete report that includes an analysis ID, target/base versions, classified breaking and non-breaking endpoint alterations, deprecation details, consumer risk assessment with estimated effort, and suggested compatibility strategies.	fail→pass	23,690	16,901	-29%	1	1	0%	4,637	4,186	-10%	0	0	—
case-03 We need to evaluate the impact of updating our payment gateway endpoints from v3.1 to v3.2. Compare the two API specifications and return an evaluation containing: the base and target version identifiers, lists of breaking changes (with paths, change types, and migration notes), non-breaking updates, deprecation warnings, severity rating, affected consumer mappings, and recommended upgrade paths.	fail→pass	19,264	18,415	-4%	1	1	0%	3,618	4,156	+15%	0	0	—
case-04 We are designing a brand new Customer Account microservice in FastAPI from scratch. Draft an OpenAPI 3.0 specification file defining GET and POST endpoints for `/v1/accounts`, including request bodies and standard 200/400 response definitions.	fail→fail	13,053	12,627	-3%	1	1	0%	2,367	3,309	+40%	0	0	—
case-05 Our Kong API Gateway is experiencing traffic spikes on the `/v1/payments` route. Provide a declarative YAML configuration for setting up a rate-limiting plugin in Kong to restrict clients to 100 requests per minute.	fail→fail	7,545	10,862	+44%	1	1	0%	1,454	2,439	+68%	0	0	—
case-06 Write a Pytest test case using `httpx.AsyncClient` that sends a POST request to `/v1/orders` with a valid JSON payload and asserts that the HTTP status code is 201 Created.	fail→fail	8,520	5,509	-35%	1	1	0%	1,738	1,630	-6%	0	0	—
case-07 We want to detect unannounced API contract changes and shadow endpoints by observing live HTTP network traffic between microservices in our Kubernetes cluster, rather than relying solely on static spec files. Which tool integration method and tool should be recommended for traffic-based change detection?	fail→pass	15,050	5,964	-60%	1	1	0%	2,631	1,597	-39%	0	0	—
case-08 Our CI pipeline needs a dedicated command-line tool to perform automated OpenAPI spec-to-spec comparisons and generate detailed structural diffs. We want a lightweight CLI utility specifically designed for this purpose. Which CLI tool should we select?	fail→pass	9,202	7,896	-14%	1	1	0%	1,760	2,067	+17%	0	0	—
case-09 Before running compatibility checks on our REST API definitions, we want to enforce organizational design rules and check spec syntax standard compliance via a CLI linter. Which CLI tool should be used for API linting?	fail→fail	8,118	3,863	-52%	1	1	0%	1,444	1,078	-25%	0	0	—
case-10 We have legacy API definitions authored in Swagger 2.0 format that need CLI-based structural comparison during our build process. Which CLI tool in our ecosystem is specifically tailored for Swagger spec comparison?	fail→fail	8,551	4,208	-51%	1	1	0%	1,478	1,363	-8%	0	0	—
case-11 Our developers want a CLI utility that intercepts local API updates during git pull requests to detect breaking changes before merging spec files. Which CLI tool should be integrated for developer change detection?	fail→pass	9,834	5,977	-39%	1	1	0%	2,024	1,634	-19%	0	0	—
case-12 In our update from `/v1/users` to `/v2/users`, we added a new request body parameter `taxIdentifier` and marked it as mandatory (`required: true`). Model this modification in JSON format structured for breaking change analysis, ensuring proper classification and categorization.	fail→pass	8,115	6,149	-24%	1	1	0%	1,782	1,943	+9%	0	0	—
case-13 In the `/v2/billing` spec update, the legacy `/v1/billing/invoices/legacy-pdf` endpoint was deleted entirely. Analyze this modification and output the result in structured API comparison JSON format.	fail→pass	6,676	7,177	+8%	1	1	0%	1,215	2,103	+73%	0	0	—
case-14 In our upcoming release of `/v1/products`, we are adding an optional query parameter `sort_order` with a default value of `asc`. Should this be categorized as a breaking or non-breaking change? Format the assessment according to our structured compatibility report format.	fail→pass	9,941	6,329	-36%	1	1	0%	1,782	1,936	+9%	0	0	—
case-15 We are flagging the `/v1/auth/token-legacy` endpoint as deprecated in our spec, with a planned sunset date in 6 months. Produce an API analysis JSON object capturing this deprecation state and timeline tracking.	fail→pass	14,130	6,215	-56%	1	1	0%	2,170	1,923	-11%	0	0	—
case-16 When 15 mobile app clients and 3 internal microservices rely on a field whose data type changed from `integer` to `string` in `/v2/orders`, evaluate the consumer impact and output a structured JSON analysis detailing affected consumers, severity rating, and migration effort.	fail→pass	13,655	9,213	-33%	1	1	0%	2,128	2,438	+15%	0	0	—
case-17 Our team needs to update the backend order processing service to payload structure v2, but external partner SDKs cannot be updated for 90 days. Recommend an architectural pattern to bridge payload differences without breaking existing client calls.	fail→fail	14,481	14,171	-2%	1	1	0%	2,205	3,112	+41%	0	0	—
case-18 We are deprecating `/v1/search` in favor of `/v2/query`, which uses GraphQL syntax. To support legacy REST clients during the 6-month transition, how should the API compatibility layer handle requests sent to the legacy path?	fail→fail	17,378	18,271	+5%	1	1	0%	2,642	3,832	+45%	0	0	—
case-19 Clients submitting requests to our API sometimes send outdated `Accept-Version` headers that are no longer natively supported by our v3 backend services. What fallback mechanism should be implemented in the compatibility layer?	fail→fail	28,564	33,044	+16%	1	1	0%	2,220	3,249	+46%	0	0	—
case-20 In the `/v2/inventory` specification, the `quantity` field changed from a 64-bit integer to a floating-point number. Analyze this spec update and provide the evaluation in structured JSON format.	fail→fail	14,474	8,954	-38%	1	1	0%	2,094	2,175	+4%	0	0	—
case-21 Perform an API compatibility evaluation comparing base version `1.0.0` and target version `1.1.0` for our customer microservice. Ensure the timestamp field in the resulting JSON output conforms to standard automated formatting.	pass→pass	8,360	14,825	+77%	1	1	0%	1,696	3,557	+110%	0	0	—
case-22 We detected three breaking field removals in `/v2/checkout`. Generate a compatibility analysis report in structured JSON format that includes concrete migration guidance for consumer teams in the recommendations list.	fail→fail	11,404	10,231	-10%	1	1	0%	2,058	2,454	+19%	0	0	—

These cases were also screened by the skill’s intent / safety pass.See the Trust review ↗Reproduce this benchmark in Colab ↗

How this skill was measured

DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted. The headline lift of +45 percentage points is the difference between those two pass rates over the 22 comparable cases.

Model measured: gemini-3.6-flash
Graded by: gemini-3.6-flash
Grading method: judged
Verification: verified
Pass rate without the skill: 4.6%
Pass rate with the skill: 50%
Cases attempted: 22
Cases counted toward lift: 22
Cases that regressed: 0
Skill version measured: v1
Run completed: 8/1/2026, 01:34 UTC

Measured example — same prompt, with vs. without the skill · from the benchmark run · case case-02

Prompt

I need a comprehensive API compatibility check between our current staging definition (`/specs/v1-legacy.json`) and the proposed release candidate (`/specs/v2-rc.json`). Output a complete report that includes an analysis ID, target/base versions, classified breaking and non-breaking endpoint alterations, deprecation details, consumer risk assessment with estimated effort, and suggested compatibility strategies.

Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.

Show both answers

SkillScore blends 4 signals1 of 4 complete

BenchmarkPass rate WITH skill on a verified run50

Live evalNeeds ≥10 evaluated traces in 30 days

AI ratingNeeds ≥10 rated traces

AdoptionNeeds ≥10 serves across ≥2 orgs in 30 days

Efficiency · separate axis (at equal correctness)+0% turns+110% tokens

Shown for transparency; not credited unless a verified run shows no correctness regression.

Backed by 1 of 4 signals — each added signal makes the score more robust.

Verified on gemini-3.6-flash · re-tested 58 days ago

Other measured skills in the registry, with their headline benchmark lift.