Agent skill · software engineering · borghei
api-design-reviewer
Review REST API designs for quality, consistency, and breaking changes. Lints OpenAPI specs, generates scorecards, and detects breaking changes between versions. Use when designing APIs, reviewing contracts, or managing API versioning.
Why this skill is useful
Adds 3 executable scripts for API linting, breaking change detection, and scoring that enhance API design quality assessment.
What it needs
Requires python installed locally. About 3k tokens when loaded. Last updated 2026-07-21. 462 stars on the source repository.
What this skill does
API Design Reviewer Comprehensive analysis and review of REST API designs against conventions, best practices, and industry standards. Helps engineering teams build consistent, maintainable, well-designed APIs through automated linting, breaking-change detection, and design scorecards. Core Capabilities API linting & convention analysis — resource naming (kebab-case URLs, camelCase fields), HTTP method usage, URL structure, status-code compliance, error-format consistency, and documentation coverage. Breaking change detection — endpoint removal, response-shape changes, field removal/rename, type changes, new required fields, and status-code changes between two spec versions, with migration guides. API design scoring — weighted scorecard across Consistency (30%), Documentation (20%), Security (20%), Usability (15%), and Performance (15%), with letter grades A–F and recommendations. When to Use Designing a new REST API or reviewing an API contract. Validating an OpenAPI/Swagger spec against REST conventions. Managing API versioning and detecting breaking changes between releases. Gating deployments on API design quality in CI. Clarify First Before producing the review, confirm these inputs. If any is unknown or vague, ASK — do not assume: [ ] Which output — lint report, design scorecard, or breaking-change detection (selects apilinter.py, apiscorecard.py, or breakingchangedetector.py) [ ] Spec file(s) — the OpenAPI/Swagger JSON, or the two versions to diff (the input the tools parse) [ ] Quality bar / CI gate — minimum grade or fail-on-breaking (sets --min-grade / --exit-on-breaking and how strict the verdict is) Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact. …
How to use it
Reference it in AdaL, Claude Code, Cursor or any coding agent — nothing to install:
@skills borghei/api-design-reviewer