Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →alirezarezvani/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.
Passed 13 of 21 test cases with the skill, and 11 of 21 without it.
and 1 more in the full report
3 fixed11 passed either way7 still failing1 broke
Tokens, turns and time describe resource use, not a dollar price.
One of 3 test cases the skill fixed. Same model, same prompt, with and without the skill.
In our v1 API, we return a `firstName` and `lastName` in the user object. For v2, we want to combine these into a single `fullName` field and remove the old fields. Is it safe to deploy this to the v1 endpoint?
| Checked | Without skill | With skill |
|---|---|---|
| Identifies that removing fields from a response payload is a breaking change | Passed | Passed |
| Recommends adding the 'deprecated: true' property to the old fields in the OpenAPI schema | Missed | Passed |
The instructions your model reads when the skill loads.
Tier: POWERFUL
Category: Engineering / Architecture
Maintainer: Claude Skills Team
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.
# 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.
test cases passed, vs 11 / 21 without
Published skills whose descriptions closely match this one, with their headline benchmark lift.
More skills from the same source and nearby in the registry, with their headline benchmark lift.