Api Design Reviewer

This is your comprehensive API design reviewer that lints OpenAPI specs, detects breaking changes between versions, and generates design scorecards across five dimensions: consistency, documentation, security, usability, and performance. It enforces REST conventions like kebab-case resources and proper HTTP method usage, flags breaking changes like removed endpoints or field type modifications, and includes detailed guidance on versioning strategies, pagination patterns, and error response formats. The scoring system is opinionated but well-reasoned, weighing consistency at 30% and giving equal weight to security and documentation. Use it during API design reviews, before releasing new versions, or when establishing API standards for your team. The real value is in catching breaking changes before they hit production.

skills.sh installs: 163
GitHub stars: 1.1K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add borghei/claude-skills --skill api-design-reviewer --agent claude-code

Installs into .claude/skills of the current project.

Files

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.