← Back to Skills Marketplace
api-diff
by
charlie-morrison
· GitHub ↗
· v1.0.0
· MIT-0
100
Downloads
0
Stars
0
Active Installs
1
Versions
Install in OpenClaw
/install api-diff
Description
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...
README (SKILL.md)
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
Usage Guidance
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.
Capability Analysis
Type: OpenClaw Skill
Name: api-diff
Version: 1.0.0
The skill bundle is a legitimate tool for comparing OpenAPI/Swagger specifications. The core logic in scripts/api_diff.py uses only Python standard libraries (json, argparse, os, sys) to parse and compare local files, with no evidence of network activity, shell execution, or data exfiltration. The SKILL.md instructions are well-aligned with the tool's purpose and do not contain any prompt-injection attempts or malicious directives.
Capability Assessment
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.
How to Use
- Make sure OpenClaw is installed (local or Docker)
- Run the install command in chat:
/install api-diff - After installation, invoke the skill by name or use
/api-diff - Provide required inputs per the skill's parameter spec and get structured output
Version History
v1.0.0
Initial release
Metadata
Frequently Asked Questions
What is 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... It is an AI Agent Skill for Claude Code / OpenClaw, with 100 downloads so far.
How do I install api-diff?
Run "/install api-diff" in the OpenClaw or Claude Code chat to install it in one step — no extra setup required.
Is api-diff free?
Yes, api-diff is completely free, licensed under MIT-0. You can download, install and use it at no cost.
Which platforms does api-diff support?
api-diff is cross-platform and runs anywhere OpenClaw / Claude Code is available (cross-platform).
Who created api-diff?
It is built and maintained by charlie-morrison (@charlie-morrison); the current version is v1.0.0.
More Skills