---
name: API Compatibility Review
slug: api-compatibility-review
category: Quality
description: API Compatibility Review assesses changes to MCP tools and REST endpoints separately for compatibility notes. Use it when a change may affect parameter schemas, response shapes, or documentation updates.
github: "https://github.com/jpicklyk/task-orchestrator/tree/main/.claude/skills/api-compat-review"
language: Kotlin
stars: 206
forks: 20
install: "npx degit https://github.com/jpicklyk/task-orchestrator/tree/main/.claude/skills/api-compat-review ~/.claude/skills/api-compat-review"
installs_to: ~/.claude/skills/api-compat-review
source_path: .claude/skills/api-compat-review/SKILL.md
collection_size: 25
category_size: 1662
collection_url: "https://dirskills.com/collections/jpicklyk/task-orchestrator"
added: 2026-09-05T05:28:53.643Z
last_synced: 2026-09-05T05:28:53.643Z
canonical_url: "https://dirskills.com/skills/api-compatibility-review"
---

# API Compatibility Review

API Compatibility Review assesses changes to MCP tools and REST endpoints separately for compatibility notes. Use it when a change may affect parameter schemas, response shapes, or documentation updates.

**Install:**

```bash
npx degit https://github.com/jpicklyk/task-orchestrator/tree/main/.claude/skills/api-compat-review ~/.claude/skills/api-compat-review
```

## README

# API Compatibility Review Framework

Assess API changes by surface — the MCP tool surface (dynamically re-discovered by clients) and the REST surface (hardcoded clients) have different compatibility models. Do not apply REST-style breaking-change caution to MCP tools, and do not apply MCP's rename-friendliness to REST.

## Step 1: Classify the Change

Determine which surface(s) the change touches:
- **MCP tools** — `application/tools/` tool definitions, `parameterSchema`, tool `description` strings
- **REST API** — `interfaces/api/v1/routes/`, `interfaces/api/v1/dto/Dtos.kt`, `openapi.yaml`

A single change (e.g., a domain model field rename) can touch both surfaces independently — assess each.

## Step 2: MCP Surface Assessment

LLM clients re-read the `tools/list` schema every session — there is no persistent client binding to break. A pure parameter rename does NOT require keeping the old name working. Verify instead:
- [ ] Every changed param's `parameterSchema` key and its arg-parsing read site stay in sync — no schema-says-X/code-reads-Y drift
- [ ] ALL first-party callers update in lockstep: plugin skills, hooks, output styles, auto-memory references, and `api-reference.md`. This doc coordination is the real cost of an MCP change, not client breakage.
- [ ] The tool `description` string accurately reflects the new behavior

## Step 3: REST Surface Assessment

HTTP clients hardcode field and param names, so compatibility DOES matter here:
- [ ] Response-shape changes are additive (new fields only) where possible
- [ ] Renames or removals of existing fields/params have an explicit migration path or version bump — not a silent break
- [ ] Note when a surface has effectively zero consumers (e.g., a days-old endpoint) so the reviewer can right-size caution instead of over-indexing on hypothetical clients
- [ ] `openapi.yaml` is updated for any REST-facing change
- [ ] `api-rest.md` is updated for any REST-facing change

## Output

Compose the `api-compatibility` note with findings from Step 2 and/or Step 3, scoped to whichever surface(s) the change actually touches. If a surface wasn't touched, say so explicitly rather than omitting it silently.