api-design-reviewlisted

# API Design Review Skill Review an API surface for design quality and evolvability before it is locked. Interface decisions are the most expensive thing to change after launch — this skill catches the mistakes that force a v2, a breaking migration, or a chatty client rewrite. It works for any API style: REST/OpenAPI, gRPC/protobuf, GraphQL, or a command-line surface. ## Step 1: Locate the API Definition If the user provided a path as an argument, use that. Otherwise glob for, in order: `**/openapi*.{yaml,yml,json}`, `**/swagger*.{yaml,yml,json}`, `**/*.proto`, `**/schema.graphql`, `**/*.graphql`, `**/schema.gql`, and route/handler files (`**/routes*.{ts,js,py,go,rb}`, `**/*router*.{ts,js,py,go}`, `**/urls.py`). If a design doc describes the API in prose (`**/api-design*.md`, `**/API.md`), accept that too. If multiple unrelated candidates exist, use AskUserQuestion to pick the surface under review. Read the full definition — every path/method, every message/service, or every type/field. ## Step 2: Detect API Style Run the inventory scan to classify the surface and get a quick count: ```bash ~/.claude/skills/api-design-review/scripts/scan-api.sh <path-or-dir> ``` Classify as one of: **REST**, **gRPC**, **GraphQL**, or **CLI**. The checklists apply to all styles; the script's inventory tells the reviewer where to focus (e.g. proto field tags for gRPC evolution, cursor pagination for REST/GraphQL collections). ## Step 3: Load Checklists Read ALL of the following chec