api-diff

Compare two OpenAPI 3.x or Swagger 2.0 specs and generate a changelog of breaking and non-breaking changes. Detect removed endpoints, new required parameters...

Security Scan

The skill's code and runtime instructions are consistent with an offline OpenAPI/Swagger diff tool; no network calls or credential access are requested, but the SKILL.md overstates YAML/support and dependency claims.

Purpose & Capability

Name/description match the included python script's behavior: it reads two local specs, normalizes them, and emits a changelog of breaking/non-breaking changes. Required binaries/env/config are none, which is proportionate. Minor mismatch: SKILL.md claims YAML support and 'stdlib only' but the script explicitly raises an error for YAML parsing (asks to convert to JSON or install PyYAML), so YAML handling is not implemented without an extra dependency.

Instruction Scope

SKILL.md tells the agent to run python3 scripts/api_diff.py old new (and offers formats/CI flags) which matches the shipped script. The instructions do not ask the agent to read unrelated files, access environment variables, or transmit data externally. The only scope issue is the documentation/behavior mismatch around YAML and external dependency requirements: the script will exit if given YAML unless PyYAML is installed.

Install Mechanism

There is no install spec (instruction-only with a bundled script). This is low risk: nothing is downloaded or written during install. Running the tool executes the included Python file locally.

Credentials

The skill requires no environment variables, credentials, or config paths. The script reads files specified on the command line and uses standard library modules only; this is proportionate to its purpose.

Persistence & Privilege

The skill is not always-on and does not request elevated or persistent privileges. It does not modify other skills or agent configs. Autonomous invocation is allowed by default but not exceptional here and does not combine with other red flags.

Assessment

This appears to be a straightforward local API diff tool: the Python script reads two spec files and prints a changelog — no network access or secrets are requested. Two things to note before installing/running: (1) SKILL.md claims YAML is supported and 'no external dependencies', but the script actually raises an error for YAML and suggests installing PyYAML or converting to JSON — so provide JSON inputs or install PyYAML if you need YAML support; (2) the tool executes code from a bundled script, so review the script (you have it) and run it on non-sensitive inputs or in an isolated environment if you are concerned about data leakage. If you want higher assurance, request the remainder of the script (it was truncated in the package listing) to verify there are no unexpected network or subprocess calls.

API Diff — Changelog Generator

Compare two OpenAPI/Swagger specs and generate a detailed changelog with breaking change detection.

Quick Diff

python3 scripts/api_diff.py old-spec.json new-spec.json

Output Formats

# Text (default)
python3 scripts/api_diff.py old.json new.json

# JSON
python3 scripts/api_diff.py old.json new.json --format json

# Markdown
python3 scripts/api_diff.py old.json new.json --format markdown

CI/CD Integration

# Fail if breaking changes found
python3 scripts/api_diff.py old.json new.json --fail-on-breaking
echo $?  # 0 = no breaking, 1 = breaking found

# Show only breaking changes
python3 scripts/api_diff.py old.json new.json --breaking-only

What It Detects

Endpoint Changes

Change	Breaking?	Description
Endpoint removed	Yes	Path+method no longer exists
Endpoint added	No	New path+method
Endpoint deprecated	No	Marked as deprecated

Parameter Changes

Change	Breaking?	Description
Required param added	Yes	New mandatory parameter
Optional param added	No	New optional parameter
Param removed (required)	Yes	Required parameter removed
Param type changed	Yes	Data type changed
Param became required	Yes	Optional → required
Param became optional	No	Required → optional

Schema Changes

Change	Breaking?	Description
Schema removed	Yes	Definition removed
Required property added	Yes	New mandatory field
Optional property added	No	New optional field
Property removed	Yes	Field removed
Property type changed	Yes	Data type changed
Enum value removed	Yes	Allowed value removed
Enum value added	No	New allowed value

Other Changes

Change	Breaking?	Description
Response code removed	Yes	HTTP status no longer returned
Response code added	No	New HTTP status
Security changed	Yes	Auth requirements changed
Server URLs changed	No	Base URL changed
API version changed	No	Info version updated

Requirements

• Python 3.6+
• No external dependencies (stdlib only)
• Input: JSON format OpenAPI 3.x or Swagger 2.0 specs