public-api-design-review Skill (samber): Review a REST API Design

Makes Claude audit a public REST API against cited rules, sort findings into Must-change or Improvement, and design a standing review process.

Installs: 9.4K; on skills.sh
Stars: 9; on GitHub
Files: 4; besides SKILL.md
Updated: Nov 2026; last repo commit

public-api-design-review makes Claude audit an existing or proposed public REST API as a checklist-driven design review. It walks eight dimensions, from resource and URI naming to pagination, filtering and one consistent error envelope, and reports findings with a cited rule and a proposed fix.

It starts when you mention an API design review, REST API consistency, endpoint naming, pagination style or API design governance. Claude asks 6 opening questions, then works through 6 steps. If it can run tools and an OpenAPI spec exists, it runs a spec linter first. The skill bundles no scripts.

Good for

API owners about to take an API public
Reviewers who want findings tied to written rules, not taste
Teams scaling from 3 to 30 API teams and needing a review process

Install public-api-design-review

Claude Code

Copy this prompt.

Install the public-api-design-review skill in Claude Code. Run this command:

/plugin marketplace add samber/developer-platform-skills
/plugin install developer-platform-skills@developer-platform-skills

Then check that it loaded and tell me how to use it.

2
Paste it into Claude Code. It shows the change and asks before running it.

Pick one route, not both, or you get every skill twice. The README asks you to install the whole set, not just public-api-design-review, because the skills reference each other and a lone skill leaves those hand-offs with nowhere to go. The plugin adds all 61 skills in the repo (counted from the repo tree). Its manifests list no hooks, agents or MCP servers.

From the project README. Source.

What's in the skill

When it loads

Audit an existing or proposed public REST API surface as a checklist-driven design review - resource and URI naming, HTTP method and status-code correctness, field-naming consistency, pagination pattern choice, filtering/sorting/field-selection conventions, one consistent error envelope, and Hyrum's-Law backward-compatibility risk - every finding bucketed Must-change or Improvement against a cited rule, plus the standing review program (audience, lifecycle triggers, reviewer authority, linting, federation). Use whenever the user mentions an API design review, REST API consistency, endpoint naming, pagination style, or API design governance - even if they never say "design review". Do NOT use for GraphQL schemas - use samber/developer-platform-skills@public-graphql-api-design instead.

Sections in SKILL.md

Clarifying questions
Audience split: surface exposure and lifecycle
Workflow
1. Scope the surface
2. Run mechanical checks first
3. Walk the checklist
4. Bucket findings through the precedent mechanism
5. Deliver the report
6. Design the standing program
Failure modes
Measurement
Invocation examples
References

Key facts

Author: Samuel Berthe
License: MIT
Version: 1.0.3
Installs on skills.sh: 9,360 (Nov 2, 2026)
GitHub stars: 9 (Nov 2, 2026)
skills.sh audits: Gen Agent Trust Hub pass; Socket pass; Snyk pass (Nov 2, 2026)
Last repo commit: Nov 1, 2026
What installs: 5 files including SKILL.md: evals/evals.json and 3 reference files. It bundles no scripts.
Needs: The other skills in the repo; the README says to install the whole set
Works in: Claude Code, Claude.ai, Codex, Cursor, Gemini CLI, and other agents through the skills CLI

What it includes

Asks 6 questions in one batch before designing anything.
Try: “Review this OpenAPI spec before we take the API public - flag anything external developers will find inconsistent.”
Opening questions
Confirms the API is REST and tags each endpoint by pagination and method checks.
Scope the surface
Runs a spec linter such as Spectral when it can run tools and a spec exists.
Runs code · Run mechanical checks first
Walks all eight review dimensions in order, starting with resource and URI naming.
Walk the checklist
Sorts findings into Must-change or Improvement; Must-change needs a cited rule.
Bucket findings through the precedent mechanism
Writes a scope header, pass/fail per dimension and a findings table with fixes.
Deliver the report
Designs an ongoing review process only when you ask for one.
Design the standing program
Advises saving decisions to developer-platform-context.md when memory is a file.
Write · Remember decisions (optional)

From the official docs

Permissions

Low risk

This skill is written advice that bundles no scripts. The one thing it may write is a decisions file, so check what Claude saves.

What it can do

Read your data
Create and change things
Delete things
Read-only mode

Watch out for

It may run a spec linter
Step 2 says that if the agent can run tools and an OpenAPI spec exists, it should run a spec linter such as Spectral before the human-judgment checks. That runs a tool on your machine, so allow it only if you want the lint pass. github.com
It may save decisions to a file
SKILL.md advises using developer-platform-context.md when memory lives in a file, and calls it an advisory reference. Check or delete that file if you do not want decisions kept. github.com
The plugin route adds all 61 skills
The README asks you to install every skill in the repo, and the repo has 61. The plugin manifests list no hooks, agents or MCP servers, and the repo tree holds none. github.com
Folder holds Markdown and one JSON file
This skill's folder has 5 files: SKILL.md, evals/evals.json and 3 reference files. It has no .py, .sh or .js file. github.com

Security advisories

No published security advisories as of Nov 2, 2026.

Technical details

Turning on read-only	No read-only setting is documented. Decline the memory-file suggestion if you want no files written.
Scopes	Asks you opening questions and works from your answers and anything you share, such as specs or docs May save settled decisions to a file named developer-platform-context.md if your memory lives in a file Step 2 says that if the agent can run tools and an OpenAPI spec exists, it should run a spec linter such as Spectral before the human-judgment checks.

Questions

How do I install public-api-design-review?

Use the install box above. The README asks you to install all 61 skills in the repo, not just this one, because the skills point to each other. In Claude Code that is the plugin route, and elsewhere the skills CLI or the client's own route installs the set.

Does public-api-design-review work in Claude.ai, Codex or Cursor?

The README documents installs for Claude.ai, Claude Code, Codex, Cursor and Gemini CLI. It also lists the skills CLI, which it calls universal for Agent Skills-compatible tools. The Claude.ai route adds the whole repo as a plugin marketplace.

Does it need an API key or any setup?

SKILL.md sets no environment variable and the folder bundles no scripts. It does ask for details of your own API or product in its opening questions.

Is public-api-design-review safe to use?

The folder holds Markdown and one JSON file, and no scripts. SKILL.md does suggest saving settled decisions to developer-platform-context.md when your memory lives in a file, so check what Claude writes. Step 2 says that if the agent can run tools and an OpenAPI spec exists, it should run a spec linter such as Spectral before the human-judgment checks. That runs a tool on your machine, so allow it only if you want the lint pass. Our advice: treat the design it produces as a draft for your team to review before you publish it.

public-api-design-review vs public-graphql-api-design?

This skill is for REST and HTTP surfaces. SKILL.md hands GraphQL schemas to public-graphql-api-design and gRPC surfaces to public-grpc-api-design, because their conventions differ.

How does it rank findings?

Two buckets, no numeric score: Must-change and Improvement. SKILL.md says a Must-change finding must cite a written rule or precedent, so a reviewer's taste alone cannot block a design.

Information

updated Nov 2, 2026

Repository: samber/developer-platform-skills
Folder: skills/public-api-design-review

samber/developer-platform-skills skills.sh

Sources

Docs, issue trackers and discussions this page is built from.

Show all 6

README · github.com
public-api-design-review SKILL.md · github.com
public-api-design-review folder · github.com
public-graphql-api-design SKILL.md · github.com
marketplace.json · github.com
plugin.json · github.com