Comprehensive REST API design review with automated linting, breaking-change detection, and design scorecards. Catches inconsistent conventions, missing versioning, and design smells before APIs ship.
Install
The skill file stays in the publisher's repository.
Paste the copied command in a terminal. It installs this SKILL.md into that agent.
npx skills add alirezarezvani/claude-skills --skill api-design-reviewer -a cursor -y
Comprehensive REST API design review with automated linting, breaking-change detection, and design scorecards. Catches inconsistent conventions, missing versioning, and design smells before APIs ship. Use when reviewing a PR that adds or changes API endpoints, auditing an existing API for v2 migration, or establishing API standards for a team.
Questions
How do I install api-design-reviewer?
Download .gemini/skills/api-design-reviewer/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does api-design-reviewer live?
The publisher keeps it at https://github.com/alirezarezvani/claude-skills.
Which agents can use api-design-reviewer?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.
Comprehensive REST API design review with automated linting, breaking-change detection, and design scorecards. Catches inconsistent conventions, missing versioning, and design smells before APIs ship. Use when reviewing a PR that adds or changes API endpoints, auditing an existing API for v2 migration, or establishing API standards for a team.
name: "api-design-reviewer"
description: "Comprehensive REST API design review with automated linting, breaking-change detection, and design scorecards. Catches inconsistent conventions, missing versioning, and design smells before APIs ship. Use when reviewing a PR that adds or changes API endpoints, auditing an existing API for v2 migration, or establishing API standards for a team."
API Design Reviewer
Tier: POWERFUL Category: Engineering / Architecture Maintainer: Claude Skills Team
Overview
The API Design Reviewer skill provides comprehensive analysis and review of API designs, focusing on REST conventions, best practices, and industry standards. This skill helps engineering teams build consistent, maintainable, and well-designed APIs through automated linting, breaking change detection, and design scorecards.
Quick Start — run the tools first
# 1. Lint an OpenAPI/Swagger spec for convention violations
python3 scripts/api_linter.py openapi.json --format json -o lint.json
# 2. Detect breaking changes between two spec versions (gate: exits non-zero with --exit-on-breaking)
python3 scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json --format json --exit-on-breaking -o breaking.json
# 3. Score overall design quality (gate: --min-grade fails below threshold)
python3 scripts/api_scorecard.py openapi.json --format json --min-grade B -o scorecard.json
Review flow: run all three, report linter findings + breaking changes + grade to the user, fix, then re-run until the linter is clean, --exit-on-breaking passes (or breaking changes are version-bumped), and the scorecard meets the agreed --min-grade. Never sign off an API review on prose alone — attach the tool outputs.
Core Capabilities
1. API Linting and Convention Analysis
Resource Naming Conventions: Enforces kebab-case for resources, camelCase for fields
HTTP Method Usage: Validates proper use of GET, POST, PUT, PATCH, DELETE
URL Structure: Analyzes endpoint patterns for consistency and RESTful design
Status Code Compliance: Ensures appropriate HTTP status codes are used
#!/bin/bash
python engineering/skills/api-design-reviewer/scripts/api_linter.py api/openapi.json
if [ $? -ne 0 ]; then
echo "API linting failed. Please fix the issues before committing."
exit 1
fi
Best Practices Summary
Consistency First: Maintain consistent naming, response formats, and patterns
Documentation: Provide comprehensive, up-to-date API documentation
Versioning: Plan for evolution with clear versioning strategies
Ignoring HTTP Status Codes: Use appropriate status codes for different scenarios
Poor Error Messages: Provide actionable, specific error information
Missing Pagination: Always paginate list endpoints
No Versioning Strategy: Plan for API evolution from day one
Exposing Internal Structure: Design APIs for external consumption, not internal convenience
Missing Rate Limiting: Protect your API from abuse and overload
Inadequate Testing: Test all aspects including error cases and edge conditions
Regular use of the linting, breaking change detection, and scoring tools ensures continuous improvement and helps maintain API quality throughout the development lifecycle.
How do I install api-design-reviewer?
Download .gemini/skills/api-design-reviewer/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does api-design-reviewer live?
The publisher keeps it at https://github.com/alirezarezvani/claude-skills.
Which agents can use api-design-reviewer?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.