Api design review

---
name: api-design-review
description: "Reviews a REST or library API design for naming, consistency, errors and versioning. Use when designing or changing an API."
---

# Api design review

A good API is predictable. Review for consistency before cleverness.

## How to work

1. List the endpoints or functions and the nouns they expose.
2. Check naming: consistent nouns, verbs, plural forms and casing.
3. Check requests and responses: required versus optional, pagination, filtering, idempotency of writes.
4. Check errors: one shape, useful messages, correct status codes.
5. Check evolution: how will a field be added or removed without breaking callers?

## Rules

- Compare against the existing API in the project before general rules.
- Flag breaking changes clearly.

## Output

A table of issues (area, problem, suggestion), then a short list of questions for the author.

How to use it

1. Download the skill.
2. Put its folder (with SKILL.md inside) in .claude/skills/api-design-review/ for just this project, or in ~/.claude/skills/ for every project.
3. Restart your tool and ask for what the skill does. It loads on its own when it fits.

Try it

Review this OpenAPI file for consistency and breaking changes.

Copy prompt