📜

API Changelog Generator

Code & Development · by AIDiveForge · Apr 20, 2026 · Beginner

Compare two OpenAPI documents and explain contract changes to API consumers.

Get a changelog with path-level evidence and breaking-change candidates.

Download skill ZIP See the worked example

Free · 2 KB · SKILL.md, instructions and example files. Provide both specifications and their OpenAPI version; a parser is needed for local schema validation.

A worked example

A small example to try before using your own data.

Input

{
  "before": {
    "GET /items": "optional query limit; response id,title"
  },
  "after": {
    "GET /items": "required query limit; response id,title,tag"
  }
}

Expected result

Breaking candidate: GET /items now requires limit; existing callers without it may fail. Response addition: tag is added; compatibility depends on whether consumers reject unknown response fields. Confirm against actual schemas and client behavior.

What to check: Identify the required-input change without automatically treating an additive response field as universally safe or breaking.

Limits: A specification diff does not prove server behavior. Test representative clients before claiming compatibility.

Worked example included. Model-specific performance and vendor compatibility have not been benchmarked.

Installation options and other formats

Install this skill

An agent skill starts with SKILL.md. The ZIP also includes its examples and any helper scripts. Drop the file into your tool of choice — or pick a different format if you use Cursor, Windsurf, Copilot, or something else.

Format Download SKILL.md

Quick install — paste into your terminal

python3 - <<'ADF_SKILL_INSTALL'
import hashlib, io, os, stat, tempfile, urllib.request, zipfile
from pathlib import Path, PurePosixPath
folder = "api-changelog-generator"
root = Path(os.environ.get('ADF_SKILL_ROOT', str(Path.home() / '.claude' / 'skills'))).expanduser()
destination = root / folder
if destination.exists() or destination.is_symlink():
    raise SystemExit('An installation already exists. Back it up and merge the ZIP deliberately.')
root.mkdir(parents=True, exist_ok=True)
request = urllib.request.Request("https://aidiveforge.com/skill/api-changelog-generator.zip", headers={'User-Agent': 'AIDiveForge-Resource-Installer/1.0 (+https://aidiveforge.com/skills/)'})
with urllib.request.urlopen(request, timeout=30) as response:
    data = response.read(8 * 1024 * 1024 + 1)
if len(data) > 8 * 1024 * 1024 or hashlib.sha256(data).hexdigest() != "555399f5b6cfab660b99c2e4f5cf74696b229501220c91df59a70c775daaef18":
    raise SystemExit('The download did not match this reviewed bundle. No files were installed.')
with zipfile.ZipFile(io.BytesIO(data)) as archive, tempfile.TemporaryDirectory(prefix='.adf-skill-', dir=root) as temporary:
    members = archive.infolist()
    if len(members) > 100 or sum(m.file_size for m in members) > 16 * 1024 * 1024:
        raise SystemExit('Unexpected archive size')
    for member in members:
        name = PurePosixPath(member.filename)
        if name.is_absolute() or '..' in name.parts or not name.parts or name.parts[0] != folder or '\\' in member.filename or stat.S_ISLNK(member.external_attr >> 16):
            raise SystemExit('Unsafe archive entry; nothing was installed')
        target = Path(temporary).joinpath(*name.parts)
        if member.is_dir():
            target.mkdir(parents=True, exist_ok=True)
        else:
            target.parent.mkdir(parents=True, exist_ok=True)
            with target.open('xb') as stream:
                stream.write(archive.read(member))
    staged = Path(temporary) / folder
    if not (staged / 'SKILL.md').is_file() or destination.exists() or destination.is_symlink():
        raise SystemExit('The skill could not be installed without replacing existing data')
    os.rename(staged, destination)
print('Installed the complete skill folder:', destination)
ADF_SKILL_INSTALL

Claude Code: ~/.claude/skills/api-changelog-generator/SKILL.md. Codex: ~/.codex/skills/api-changelog-generator/SKILL.md. Keep the complete ZIP folder when helper scripts are included.

🧠 Why it works

Identify the required-input change without automatically treating an additive response field as universally safe or breaking.

⚙️ How it works

Validate both documents and resolve local references before comparing operations.

Match operations by path and method, then compare parameters, request bodies, responses and security requirements.

Treat removal, new required inputs and narrower accepted values as possible breaking changes; distinguish response additions from request restrictions.

Keep implementation behavior separate from the documented contract and flag unresolved references.

Return consumer actions and exact before/after locations; do not label every textual edit as a breaking change.

Description

Get a changelog with path-level evidence and breaking-change candidates.

Provide both specifications and their OpenAPI version; a parser is needed for local schema validation.

Limits: A specification diff does not prove server behavior. Test representative clients before claiming compatibility.