Skip to main content
skill CX Codex

api-design-review — Claude Code skill: review and install

api-design-review — a skill for Claude Code reviews HTTP APIs, SDKs, and CLIs. It runs when asked to assess an API design, inspect a spec, or judge whether a change is safe to ship.

MIT ★ 541 updated 2026-11-09

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add dotslashsimran/simcraft --skill api-design-review -a claude-code
Open on GitHub

What api-design-review does

The skill examines an API’s public shape and writes its findings to review.md. The report includes a scorecard, prioritized issues with suggested rewrites, risks from potentially breaking fixes, and specific strengths. Scripts lint OpenAPI files, inspect an SDK’s public interface, and sort differences between two spec versions by compatibility risk.

The scripts require Python 3.9 or later. YAML support uses PyYAML when installed; otherwise a small built-in parser handles it. YAML anchors or tags require PyYAML or a JSON copy. The SDK script imports the Python package, so run it only on code you trust. Script results can include false positives, which need review against the API.

What it helps with

  • spot inconsistent names and resource models in an API
  • classify changes between two OpenAPI versions
  • find gaps in error responses, pagination, or retries
  • inspect an SDK’s public classes and functions
  • check CLI conventions and failure exit codes

Example prompts for the agent

  • Review the API in openapi.yaml and save the report as review.md.
  • Compare old.json with new.yaml and list breaking changes.
  • Inspect the public interface in dist/index.d.ts.

How to install api-design-review

1Skills CLI (Vercel)

npx skills add dotslashsimran/simcraft --skill api-design-review -a claude-code

2Manually: put the files in place

~/.claude/skills/api-design-review/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/api-design-review/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about api-design-review

How do I install api-design-review in Claude Code?

Run npx skills add dotslashsimran/simcraft --skill api-design-review -a claude-code. The skill file is at ~/.claude/skills/api-design-review/SKILL.md.

What does api-design-review do?

It reviews HTTP APIs, SDKs, and CLIs, and checks compatibility risks between spec versions. Findings are written to review.md.

What does api-design-review need to run?

Its scripts require Python 3.9 or later. YAML files with anchors or tags need PyYAML or a JSON copy.

Source text

SKILL.md · MIT
---
name: api-design-review
description: Review the design of an API surface, meaning an HTTP API (OpenAPI spec or route code), an SDK's public classes and functions, or a CLI. Checks naming and consistency, resource modelling, error design (stable codes, RFC 9457 problem details, request ids), versioning and breaking changes, pagination, filtering, idempotency and retries, rate limits, timeouts, long-running operations, webhooks, auth, partial updates, ID, time and money formats, SDK ergonomics and CLI conventions. Uses scripts to lint OpenAPI files, classify changes between two spec versions as breaking or safe, and dump an SDK's public surface. Writes review.md with a scorecard, ranked findings with rewrites, a breaking-change risk list and what is good. Use when the user says "review my API", "API design", "is this a breaking change", "OpenAPI review", "check my spec", "SDK ergonomics", "review my SDK", "review my CLI", or asks whether an API change is safe to ship. For onboarding and time to first success, use dx-audit instead.
---

# API design review

This skill reviews the shape of an API, which is the names, resources, errors, formats and rules that every user has to learn. Most API design mistakes are cheap to fix before launch and expensive after it, because fixing them breaks clients. The review therefore puts the findings that would be breaking to fix later at the top.

The judgement lives in `reference.md`, which has the scoring rubric, the severity scale, the rules for each area with citations to public guidelines (Google AIP, Microsoft REST API Guidelines, Stripe's API conventions, Zalando RESTful API Guidelines, IETF RFCs), and before and after rewrites. Read the sections that match the API before writing findings.

The scripts need only Python 3.9 or newer and the standard library. They read JSON, and they read YAML with PyYAML if it is installed or with a small built-in parser if it is not. Files that use YAML anchors or tags need PyYAML or a JSON copy.

## 1. Find out what to review

Ask one question at a time, and only for what is missing:

- **What is the surface?** It can be an OpenAPI file, route code, an SDK (a Python package name or a `.d.ts` file), or a CLI (`--help` output or the command source).
- **Who uses it?** Public, partner, or internal with one client. This sets severity (reference.md section 2).
- **Is it launched?** Before launch, recommend breaking fixes freely. After launch, every fix must come with a migration path.
- **Is there an old version to compare against?** If yes, run the diff in step 3.

## 2. Run the tools

Set `S=~/simcraft/skills/coding/api-design-review/scripts`.

**OpenAPI lint:**
```
python3 $S/lint_openapi.py openapi.yaml            # text
python3 $S/lint_openapi.py openapi.yaml --format md
python3 $S/lint_openapi.py openapi.yaml --fail-on high   # exit 1 for CI
```
It checks path and field case consistency, plural collections, verbs in paths, error schemas (missing, inconsistent, no machine code, no request id), undocumented 4xx and 5xx, list endpoints with no pagination or a bare array response, mixed ID and time formats, money as floats, creating POSTs without an Idempotency-Key, PATCH bodies with required fields, 429 without Retry-After, duplicate or missing operationIds, and unsigned webhooks.

**SDK surface:**
```
python3 $S/sdk_surface.py my_package [--path src] [--depth 2]
python3 $S/sdk_surface.py dist/index.d.ts
```
It prints the public tree (modules, classes, signatures, properties, constants) and hints about boolean flag arguments, long positional parameter lists, mutable defaults, `any`, optional parameters before required ones, timeouts that default to waiting forever, error classes with no common base, and missing docs. Importing a Python package runs its import code, so only run it on code the user trusts.

**For a CLI**, there is no script. Run `<tool> --help` and the help for each subcommand, try one command with `--json` and with output piped to a file, check the exit code after a failing command (`echo $?`), and compare against reference.md section 17.

**For route code with no spec**, export a spec if the framework can (reference.md section 18). Otherwise build the endpoint list by reading the routes.

The scripts find patterns, and they also produce false positives. Read every finding, drop the ones that are wrong for this API, and say which areas the scripts cannot check (behaviour, defaults, docs quality, real latency).

## 3. Check breaking changes

When there are two versions:
```
python3 $S/breaking_diff.py old.json new.yaml [--format md]
```
It sorts every change into BREAKING, RISKY or SAFE, says why, shows where changed shared schemas are used, and says what semver bump the changes need. It exits 1 if anything is breaking, so it can run in CI on every pull request.

The script cannot see behaviour changes such as a new default value, a different sort order, stricter server-side validation that the spec does not show, or new side effects. Ask about those directly.

When there is only one version, write the breaking-change risk list from the lint instead. It lists the findings whose fix would itself be breaking (bare array lists, integer IDs, missing pagination, error shape, field renames), so the user knows what to fix before launch.

## 4. Write review.md

Write `review.md` next to the API source unless the user says otherwise. Use this structure, and see `examples/review.md` for a full example:

1. **Summary.** Two or three sentences with the overall verdict and the top three fixes.
2. **Scorecard.** A table with each area from the reference.md rubric, a 0 to 3 score, and one line of reason. Mark areas that do not apply as n/a.
3. **Findings, ranked by severity (P0 to P3).** For each finding, give where it is, what is wrong, why it costs users something, the precedent from a public guideline, and a concrete rewrite (before and after for the path, schema, error body or call site). Group repeated cases into one finding with a list of locations.
4. **Breaking-change risk list.** Diff results if there were two versions. Otherwise, the fixes from the findings that would break clients, each with a migration path (alias, deprecation header, sunset date, new version).
5. **What's good.** Specific things the API does well, so the team keeps doing them. Write this section honestly and specifically, with no padding.
6. **Not checked.** What the review could not see.

Keep findings concrete. "Errors are inconsistent" is not a finding. "`POST /orders` returns `{error: {msg}}` and `GET /orders/{id}` returns `{message}`, so clients need two error handlers" is a finding.

## 5. Hand over

Show the user the summary and the top findings in chat, and give the path to `review.md`. If they want to fix things, start with the P0 findings, then the P1 findings that are breaking, and re-run the lint and the diff after each change.

© dotslashsimran · MIT · dotslashsimran/simcraft

Similar skills

All skills for Backend and APIs →

From the same set24

The whole set →
reverse-engineer-video The reverse-engineer-video Claude Code skill breaks down a reference clip into shots, camera moves and editing beats. Invoke it to inspect a cut, plan a remake or compare one with the original. CX Codex +1 ★ 541repo stars system-design-from-scratch system-design-from-scratch — a skill for Claude Code that builds minimal distributed architectures, verifies invariants under simulated node failures, and stress-tests them with real metrics. CX Codex +1 ★ 541repo stars paper-to-runnable The paper-to-runnable Claude Code skill turns a research paper into a minimal implementation of its central idea. It activates for requests to build or reproduce a paper, including from an arXiv link or local PDF. CX Codex +1 ★ 541repo stars codebase-map The codebase-map Claude Code skill maps an unfamiliar repository and traces a real request through it. Ask it to explain the project structure, locate a code path, or onboard a new teammate. CX Codex +1 ★ 541repo stars code-loop The code-loop Claude Code skill turns three.js scenes and GLSL shaders into looping videos. It activates for requests to make generative animations or GIFs that repeat without a visible cut. CX Codex +1 ★ 541repo stars dx-audit dx-audit — a Claude Code skill audits the onboarding path for an SDK, API, CLI, or framework using its official docs. It follows one task in a clean environment and records friction, errors, and time to first success. CX Codex +1 ★ 541repo stars rough-cut This Claude Code skill builds a rough cut from talking footage. It kicks in for requests to trim pauses, filler words, repeats, or weak takes. CX Codex +1 ★ 541repo stars perspective-illusion This Claude Code skill creates looping illustrated 3D videos built around a perspective illusion. It activates for requests involving a dolly zoom, a flat-to-3D transition, or a similar optical-illusion clip. CX Codex +1 ★ 541repo stars

Project sponsors

Companies that keep this analytics open