API Design Review

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 p

517 stars 39 forksSoftware Development

Install

skills CLI (Claude Code, Cursor, Codex and more)
npx skills add dotslashsimran/simcraft --skill api-design-review
Manual install
git clone --depth 1 https://github.com/dotslashsimran/simcraft.git /tmp/simcraft
mkdir -p ~/.claude/skills
cp -r /tmp/simcraft/skills/coding/api-design-review ~/.claude/skills/api-design-review

Personal skills live in ~/.claude/skills. Use .claude/skills in a project folder to share a skill with your team.

From the SKILL.md

# 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.
Read the full skill on GitHub

Details

Skill name
api-design-review
Path
skills/coding/api-design-review/SKILL.md
License
MIT
Repo updated
9 November 2026

FAQ

What does the API Design Review skill do?

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 p

How do I install the API Design Review skill?

skills CLI (Claude Code, Cursor, Codex and more): npx skills add dotslashsimran/simcraft --skill api-design-review. Skills go in ~/.claude/skills (personal) or .claude/skills (project), and Claude loads them automatically when a task matches the description.

Is API Design Review popular?

It lives in dotslashsimran/simcraft, which has 517 GitHub stars and 39 forks.

Related skills

Benchmark Honestly

517

dotslashsimran/simcraft

Build benchmarks that survive scrutiny and catch the classic lies (dead code elimination, lazy results, constant folding, warm caches, coordinated omission, averages hiding GC pauses, unequal work, noisy machines). Defines the question first, controls and discloses the environment, uses warmups, interleaved repeats, medians, bootstrap confidence intervals and Mann-Whitney tests, and ends with a one-line verdict that includes the CI. Bundles a command runner, an environment reporter and an open-loop latency tester. Use when the user says "benchmark this", "is this faster", "compare performance"

Software Development39

Bisect Anything

517

dotslashsimran/simcraft

Find the exact commit (or dependency version, config value, or input) that caused a regression by turning it into an automatic pass/fail check and running git bisect run in a separate worktree, then shrink the bad commit to the hunk that matters and explain it. Handles failing tests, changed output, slowdowns, crashes, visual changes, server behaviour, flaky checks, unbuildable commits and merge-heavy history. Use when the user says "what broke this", "find the commit that", "when did this start", "it used to work", "regression", "git bisect", "which version broke it", or "which change made it

Git & Code Review39

Brand Kit

517

dotslashsimran/simcraft

Learn a company's brand design from its live website (colours, fonts with the real font files, logo, button and card shapes, texture, image style) and save it as a reusable kit that vox-explainer and image-gen apply automatically. Use FIRST, before any brand or sponsored video, sticker, graphic or asset for a company (e.g. "a video for Devin", "ChatGPT-style stickers", "match their brand"), or when asked to get, learn, extract or match a brand's look.

Frontend & Design39

Tree Generator

360

TanStack/intent

Use when turning an approved domain_map.yaml and skill_spec.md into a full-library skill tree or explicitly auditing its structure and dependencies. For agreed batches and source-driven guidance updates, use generate-skill instead.

Software Development26

Code Loop

517

dotslashsimran/simcraft

Make a seamless, perfectly looping generative video in code, from a three.js scene or a raw GLSL fragment shader, rendered frame-perfect with jittered anti-aliasing and motion blur, then checked for a visible seam, freezing and blinking. Use when asked for a "seamless loop", a "perfect loop", "generative art video", a "shader loop", "three.js animation to video", to "render a looping animation", a looping GIF from code, or any code-driven animation that has to loop without a visible cut.

Software Development39

Generate Skill

360

TanStack/intent

Use when creating or extending library skill batches, updating guidance after library source or docs change, configuring repository skill distribution, or acting on an Intent review report, including when the maintainer asks only for the library change. For full-library discovery or taxonomy design, use domain-discovery; for generating an approved full-library tree, use tree-generator.

Software Development26

Browse the most popular Claude skills, all software development skills, or write your own with the skills generator.