# API Compat

> Detect breaking changes in APIs — protobuf, OpenAPI/Swagger, GraphQL schemas, or Go exported interfaces. Use when the user says "API compat", "breaking changes", "check API compatibility", "proto breaking", "schema breaking", "is this breaking", "backward compatible", "API diff", "contract check", or when API definition files have been modified.

- Skill: `indrasvat/api-compat` (Agent Skill)
- Install (CLI): `npx skillmds@latest add indrasvat/api-compat`
- Raw SKILL.md: https://api.skillmd.com/api/skills/indrasvat/api-compat/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Integrations & APIs
- Author: indrasvat (https://skillmd.com/u/indrasvat)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/indrasvat/api-compat

---


# API Compatibility Check

Detect breaking changes in API definitions. Read-only analysis, safe to re-run.

## 1. Prerequisites

Check for specialized tools via `command -v`: `buf` (protobuf), `oasdiff` (OpenAPI). Report availability. If missing, fall back to manual git-diff analysis and note which tool would improve accuracy.

## 2. Scope

If `$ARGUMENTS` names specific files, analyze only those. Otherwise, find API files changed since base branch using `git diff --name-only $(git merge-base HEAD main)`. Detect by pattern:

| Pattern | Type |
|---------|------|
| `*.proto` | Protobuf |
| `openapi.yaml`, `swagger.json`, `*.openapi.*`, `*.swagger.*` | OpenAPI |
| `*.graphql`, `*.gql` | GraphQL |
| `*.go` with exported types changed | Go exported API |

Stop with a clear message if no API files are found in scope.

## 3. Baseline

Compute and print the merge-base: `git merge-base HEAD main`. For each file in scope, diff working tree against that baseline using `git diff <merge-base> -- <file>`.

## 4. Analysis by Type

### Protobuf
If `buf` is available, run `buf breaking --against .git#ref=<merge-base>`. Otherwise, manually inspect diffs for:
- BREAKING: field number reuse, field removal, type change, adding required fields
- SAFE: new optional field, new enum value with no renumbering

### OpenAPI
If `oasdiff` is available, run `oasdiff breaking <base-file> <current-file>`. Otherwise, manually inspect diffs for:
- BREAKING: removed endpoint, changed HTTP method, removed parameter, new required parameter, response schema narrowing
- SAFE: new optional parameter, new endpoint, added response fields

### GraphQL
Manually inspect diffs for:
- BREAKING: removed type/field, changed return type, new required argument, removed enum value
- SAFE: new optional field/argument, new type, new enum value

### Go Exported API
Manually inspect diffs for:
- BREAKING: removed exported symbol, changed function signature, changed interface method set, changed struct field types
- SAFE: new exported symbol, new method on concrete type

## 5. Output

Print a summary line first: total changes found, how many breaking. Then print a compatibility report table:

```
| Change | File:Line | Type | Severity |
```

Severity values: BREAKING, WARN, SAFE. Use WARN when a change is technically non-breaking but likely to cause client issues (e.g., deprecating a widely-used field, adding an enum value to a closed enum).

## 6. Idempotency

Read-only. No files created, modified, or deleted. Safe to re-run at any time.

`$ARGUMENTS`