api-design-reviewer

# 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 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 resou...