Skip to main content
skill CX Codex

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

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add borghei/Claude-Skills --skill api-design-reviewer -a claude-code
Open on GitHub

What 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-code

2Manually: put the files in place

~/.claude/skills/api-design-reviewer/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/api-design-reviewer/

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.

api-design-reviewer Alireza Rezvani api-design-reviewer audits REST API designs, spots breaking changes between spec versions, and calculates quality scorecards. Useful when reviewing PRs with endpoint changes or planning a v2 migration. CX Codex +1 768installs public-api-design-review Samuel Berthe public-api-design-review runs a REST API surface, shipped or still on paper, through an eight-part checklist and splits every finding into Must-change or Improvement. CX Codex +1 10,200installs rest-api-design aj-geddes The rest-api-design skill gives your agent rules for resource naming, HTTP methods, status codes and versioning when you build new endpoints or clean up old ones. CX Codex +1 2,100installs api-design Agent Skills Team api-design is a Claude Code skill that designs or refactors REST and GraphQL API contracts. It runs before implementation, while the interface shape is being agreed on. CX Codex +1 390installs design-rest-api davila7 design-rest-api designs RESTful API architectures, endpoints, authentication flows, and OpenAPI documentation directly from project code. CX Codex +1 559installs openapi-expert personamanagmentlayer openapi-expert guides OpenAPI 3.0 and 3.1 spec design, schema polymorphism, linter rules, and code generation. CX Codex +1 282installs openapi-spec-writer curiositech openapi-spec-writer writes OpenAPI 3.0 and 3.1 specifications for REST APIs. Useful for API-first design, contract definition, and setting up Swagger or Redoc documentation. CX Codex +1 175installs

From the same set120

The whole set →
ml-ops-engineer ml-ops-engineer is a skill for MLOps automation: deploying models, orchestrating training pipelines, monitoring feature drift, and configuring feature stores. It addresses gaps in ML deployment workflows. CX Codex +1 180installs ma-playbook ma-playbook is a Claude Code skill that structures M&A target assessment, due diligence, and deal structuring. CX Codex +1 179installs cto-advisor cto-advisor — a skill for technology strategy, team scaling and architecture decisions. Helps plan engineering growth, prioritise technical debt and evaluate vendors. CX Codex +1 177installs database-designer The database-designer skill for Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, and OpenCode reviews SQL schemas, suggests indexes, and creates migrations. Use it for DDL reviews, index tuning, or schema diffs. CX Codex +1 176installs information-security-manager-iso27001 information-security-manager-iso27001 is a Claude Code skill for designing and auditing an ISO 27001:2022 ISMS, covering risk assessment, Annex A controls, and certification readiness. CX Codex +1 166installs agent-designer agent-designer — a skill for Claude Code and related platforms that plans multi-agent architectures. It generates tool definitions for Anthropic and OpenAI, diagrams communication flows, and parses runtime logs. CX Codex +1 161installs marketing-psychology The marketing-psychology skill uses behavioral psychology and mental models to diagnose marketing friction. Use it for landing pages, pricing, email, ads, and conversion work. CX Codex +1 151installs aws-solution-architect aws-solution-architect — a skill for Claude Code, Codex, and Cursor that designs AWS architectures and outputs IaC templates. Tailors cloud patterns to workload demands and flags infrastructure savings. CX Codex +1 150installs

Project sponsors

Companies that keep this analytics open