api-design-reviewer
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.
Profile →npx skills add alirezarezvani/claude-skills --skill api-design-reviewer --agent claude-code
Same command for any agent — swap --agent for codex, cursor, copilot.
Weekly change comes from our own snapshots, not the repository page — it measures attention, not adoption.
# 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 ```bash # 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 bre
- Overview
- Quick Start — run the tools first
- Core Capabilities
- 1. API Linting and Convention Analysis
- 2. Breaking Change Detection
- 3. API Design Scoring and Assessment
- REST Design Principles
- Resource Naming Conventions
- HTTP Method Usage
- URL Structure Best Practices
- Versioning Strategies
- 1. URL Versioning (Recommended)
- 2. Header Versioning
- 3. Media Type Versioning
python3 scripts/api_linter.py openapi.json --format json -o lint.json python3 scripts/breaking_change_detector.py openapi-v1.json openapi-v2.json --format json --exit-on-breaking -o breaking.json python3 scripts/api_scorecard.py openapi.json --format json --min-grade B -o scorecard.json 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
What does the api-design-reviewer skill do?
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.
How do I install it?
Run `npx skills add alirezarezvani/claude-skills --skill api-design-reviewer --agent claude-code` — it drops the skill into your project so the agent can pick it up. Swap the --agent value for codex, cursor or copilot if you use one of those.
Where does this skill come from?
From alirezarezvani/claude-skills, a repository with 23,791 stars. We read it straight from the repository tree rather than a submitted listing, so what you see here is what is actually published.
Is a popular skill a good skill?
Not necessarily. Stars measure attention, not adoption — a repository can trend for a week and be abandoned. That is why we show the weekly change from our own snapshots next to the total, instead of a single flattering number.