Skip to content
Agentmart
Submit a tool

api-design-reviewer

lint an OpenAPI/REST API spec for convention violations, detect breaking changes between two spec versions, and score overall design quality — use when…

Skill by Hugofsco

IndexedMIT
Write a review

Install

Works with Claude Code, Claude apps, Codex, Cursor, Gemini CLI, GitHub Copilot, VS Code, OpenCode, Goose, Windsurf. Read the repository before you give any tool access to your data.

npx agentmarket install skill/hugofsco-api-design-reviewer

Asks which of your tools to add it to (Claude Code, Codex, Cursor, VS Code, Windsurf, Gemini CLI, Claude Desktop) and shows the change first. See https://agentmart.dev/cli.

Get the weekly diff

The weekly diff: one email a week with new agent tools, notable updates and grade changes, plus security alerts for tools you follow. Double opt-in, one-click unsubscribe.

We use your email only for this newsletter. Privacy

About

lint an OpenAPI/REST API spec for convention violations, detect breaking changes between two spec versions, and score overall design quality — use when reviewing an API change, planning a v2, or before shipping a new endpoint

Use cases: design, backend

Reviews

Write a review

No reviews yet. Installed it? Reviews come from verified installers only. How reviews work

Permissions

What this skill can do and what it asks for, from its SKILL.md. Checked Oct 25, 2026.

Tools
No tools found
Secrets
None asked for
Install scripts
None found
Runs as
Python package

Network hosts it talks to 1

  • codeload.github.com · found in install command

Files it touches

  • ~/.claude/skills/api-design-reviewer

What's inside

Skill name
api-design-reviewer
Description
lint an OpenAPI/REST API spec for convention violations, detect breaking changes between two spec versions, and score overall design quality — use when reviewing an API change, planning a v2, or before shipping a new endpoint
License
MIT
Instructions
17 lines in SKILL.md · view on GitHub

Before installing

  • Ships executable scripts

Files (4)

  • SKILL.md
  • api_linter.py · scripts/
  • api_scorecard.py · scripts/
  • breaking_change_detector.py · scripts/

SKILL.md (first lines)

# API design reviewer

1. **Lint the spec:** `python3 skills/api-design-reviewer/scripts/api_linter.py <openapi.json> --format json`
   — naming conventions, HTTP method usage, error-format consistency, doc gaps.
2. **Check for breaking changes between versions:**
   `python3 skills/api-design-reviewer/scripts/breaking_change_detector.py <v1.json> <v2.json> --exit-on-breaking`
3. **Score design quality:** `python3 skills/api-design-reviewer/scripts/api_scorecard.py <openapi.json> --min-grade B`
   — weighted across consistency/docs/security/usability/performance, letter grade A-F.

Run all three, report findings + grade, fix, re-run until the linter is clean and the
scorecard clears the bar — don't sign off on prose alone.

Quick conventions worth remembering without opening a reference: nouns not verbs in URLs
(`/users` not `/getUsers`), kebab-case resources, version in the URL (`/api/v1/...`),
paginate every list endpoint, never remove a field or make an optional field required
without a version bump.

From Hugofsco/oceano, MIT.

More from Hugofsco/oceano

Signals

Stars
0
Forks
0
Open issues
0
Last commit (this folder)
Jul 5, 2026 (3 months ago)

From GitHub (fetched Oct 24, 2026).

Details

License
MIT
Repository
github.com/Hugofsco/oceano
First seen
Oct 24, 2026
Last checked
Oct 24, 2026
Source
GitHubgithub-graphql

More from Hugofsco

Cite this page

api-design-reviewer skill. Agent Mart. https://agentmart.dev/skills/hugofsco-api-design-reviewer (last updated 2026-10-24)