REST API Design Review skill for Claude and Codex

REST API Design Review as an AI skill. It asks for The API, Consumers, Existing clients and 2 more, then does the rest. Free to install in Claude or Codex.

Install it once and Claude or Codex runs it for you. When your request matches, your AI loads the skill, asks for anything it is missing, and works through the template itself. Prefer to fill it in by hand? See the full prompt template.

Download the skill (.zip) · View SKILL.md

When it is used

Use when a REST API design or OpenAPI draft needs a review of naming, status codes, pagination, error format, versioning, and auth before clients depend on it. Do not use for implementing the endpoints or designing a GraphQL schema. Related topics: coding, technical.

What it will ask you for

• The API (longer free text)
• Consumers (free text, e.g. "Who calls it and from where")
• Existing clients (choose one: Yes, No)
• Areas (choose any: Resource naming, Verbs and status codes, Pagination, Filtering, Error format, Versioning, Authentication, Idempotency)
• Auth method (choose one: API key, Bearer token, OAuth, Session cookie, None)

How it works

1. Read the full route list and write down the patterns in use for naming, nesting, pagination, and errors.
2. Check each route's verb, status codes, and idempotency against those patterns and against HTTP semantics.
3. Define the single pagination style and single error body the whole API should use.
4. Mark every proposed change as breaking or safe for existing clients and sketch a versioning path for the breaking ones.
5. Return a findings table and the proposed contract for the five most important routes.

What you get

A findings table with route, issue, fix, and breaking or safe, followed by the proposed contract for the five most important routes.

What it watches out for

• Reviewing routes one at a time and missing that three of them paginate in different ways.
• Using 200 with an error body for failures, which breaks every client that trusts status codes.
• Proposing a clean rename without checking it is a breaking change for live clients.

How to install

Claude.ai and the Claude desktop app

1. Download the skill .zip.
2. Open Settings, then Capabilities, and find Skills.
3. Choose Upload skill and select the .zip.
4. Ask Claude for help with the task. It loads the skill when your request matches.

Claude Code

1. Download the skill .zip.
2. Unzip it into ~/.claude/skills/ (or .claude/skills/ inside a project).
3. Start a new session. Claude Code loads the skill when your request matches.

Codex

1. Download the skill .zip.
2. Unzip it into ~/.agents/skills/ (or .agents/skills/ inside a project).
3. Codex picks it up on its own. Type $ and the skill name to use it, or just ask for the task.

Cursor

1. Download the Cursor rule (.mdc).
2. Save it in .cursor/rules/ inside your project.
3. Cursor's agent applies the rule when your request matches its description.

AGENTS.md (Codex, Cursor, and other coding agents)

1. Copy the AGENTS.md section.
2. Paste it into AGENTS.md at the root of your repository, creating the file if needed.
3. Coding agents that read AGENTS.md follow it when your request fits.