api-design-reviewer · borghei — Claude Code skill: what it does, how to install
api-design-reviewer — a skill for Claude Code inspects OpenAPI specs, catches breaking schema changes between versions, and grades REST API architecture maturity.
LicenseRef-MIT-Commons-Clause 167 installs ★ 1,183 updated 2026-11-08
npx skills add borghei/Claude-Skills --skill api-design-reviewer -a claude-codeWhat api-design-reviewer does
Works across Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode through three bundled Python CLIs. The api_linter.py script validates paths, HTTP verbs, error payloads, and naming rules, catching issues like verbs in URL paths or wrong field casing.
The breaking_change_detector.py utility compares two API spec versions to spot removed endpoints, altered data types, or newly required fields. With --exit-on-breaking, it exits with code 1, making it suitable for CI pull request gates.
Your environment requires Python and valid OpenAPI or Swagger JSON files; malformed JSON or unreadable paths exit immediately with code 2. The third tool, api_scorecard.py, measures design maturity across five weighted areas to deliver a letter grade from A to F.
What it helps with
- catch breaking API changes between two schema releases
- audit REST paths and HTTP methods against standard conventions
- score API completeness across security, docs, and usability
- fail continuous integration checks on contract violations
Example prompts for the agent
- Run api_linter.py on openapi.json to check REST conventions
- Diff v1.json and v2.json with breaking_change_detector.py
- Calculate an architecture maturity score for swagger.json
How to install api-design-reviewer
1Skills CLI (Vercel)
npx skills add borghei/Claude-Skills --skill api-design-reviewer -a claude-code2Manually: put the files in place
~/.claude/skills/api-design-reviewer/SKILL.mdCopy the whole skill folder; for one project use .claude/skills/api-design-reviewer/
1Skills CLI (Vercel)
npx skills add borghei/Claude-Skills --skill api-design-reviewer -a codex2Manually: put the files in place
.agents/skills/api-design-reviewer/SKILL.mdFor all projects use ~/.agents/skills/
1Skills CLI (Vercel)
npx skills add borghei/Claude-Skills --skill api-design-reviewer -a cursor2Manually: put the files in place
.cursor/skills/api-design-reviewer/SKILL.mdCursor also reads .agents/skills/ and .claude/skills/
1GitHub CLI
gh skill install borghei/Claude-Skills engineering/api-design-reviewer/SKILL.md2Manually: put the files in place
.github/skills/api-design-reviewer/SKILL.md1Skills CLI (Vercel)
npx skills add borghei/Claude-Skills --skill api-design-reviewer -a gemini-cli2Platform CLI
gemini skills install https://github.com/borghei/Claude-Skills --path engineering/api-design-reviewerManually: put the files in place
.devin/skills/api-design-reviewer/SKILL.mdThe legacy .windsurf/skills/ path still works
Skills CLI (Vercel)
npx skills add borghei/Claude-Skills --skill api-design-reviewer -a opencodeClaude.ai
Zip the folder and upload it in Settings → Capabilities → Skills
Step by step, with commands for each platform: How to install skills in Claude Code: five ways
Questions about api-design-reviewer
How do I install api-design-reviewer in Claude Code?
Run npx skills add borghei/Claude-Skills --skill api-design-reviewer -a claude-code.
What does api-design-reviewer do?
It provides three Python scripts to lint OpenAPI contracts, detect breaking changes across versions, and generate a weighted maturity scorecard from A to F.
How do the linter and the scorecard differ?
The linter flags rule violations like RPC verbs in paths, while the scorecard measures completeness including docs, security, and pagination coverage.
Similar skills
All skills for Backend and APIs →api-design-reviewer by other authors comes first.