Loading skill
Install any skill in seconds. Free to start, no credit card required.
Get Started Free →Review REST API designs for quality, consistency, and breaking changes. Lints OpenAPI specs, generates scorecards, and detects breaking changes between versions. Use when designing APIs, reviewing contracts, or managing API versioning.
.claude/skills/borghei-api-design-reviewer/SKILL.md| Test case | Without → With | Effect | Δ tokens | Δ turns |
|---|---|---|---|---|
| case-01 | ✗→✓ | ▲ Improved | 164% | 0% |
| case-02 | ✗→✓ | ▲ Improved | 45% | 0% |
| case-03 | ✗→✓ | ▲ Improved | 13% | 0% |
| case-04 | ✗→✓ | ▲ Improved | 34% | 0% |
| case-05 | ✗→✓ | ▲ Improved | -23% | 0% |
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.
Before producing the review, confirm these inputs. If any is unknown or vague, ASK — do not assume:
api_linter.py, api_scorecard.py, or breaking_change_detector.py)--min-grade / --exit-on-breaking and how strict the verdict is)Stop rule: ask only the 2-3 that most change the output. If the user says "just draft it," proceed and list your assumptions at the top of the artifact.
| Tool | Purpose | Command | |------|---------|---------| | api_linter.py | Lint an OpenAPI/Swagger JSON spec for REST conventions and best practices | python scripts/api_linter.py openapi.json --format json | | breaking_change_detector.py | Detect breaking changes between two spec versions (with migration guides) | python scripts/breaking_change_detector.py v1.json v2.json --exit-on-breaking | | api_scorecard.py | Score API design quality across 5 weighted dimensions (A–F grades) | python scripts/api_scorecard.py openapi.json --min-grade B |
Load the reference that matches the task — keep this file lean and pull detail on demand:
This skill covers:
This skill does NOT cover:
api-test-suite-builder)senior-security in engineering/)| Skill | Integration | Data Flow | |-------|-------------|-----------| | engineering/api-test-suite-builder | Generate test cases from linter findings | Linter issues feed into test plan priorities for endpoint validation | | engineering/changelog-generator | Document breaking changes in release notes | Breaking change detector output provides structured change data for changelogs | | engineering/ci-cd-pipeline-builder | Gate deployments on API quality | Scorecard grade and linter exit codes integrate as pipeline quality gates | | engineering/senior-backend | Review API implementation against design | Scorecard recommendations guide backend refactoring decisions | | engineering/code-reviewer | Enrich PR reviews with API analysis | Linter and breaking change reports attach to PR review comments | | engineering/release-manager | Validate version bumps match change severity | Breaking change detector severity levels inform semver version decisions |
| Case | Status | Duration (ms) | Turns | Tokens | Tool calls | ||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| Without | With | Δ | Without | With | Δ | Without | With | Δ | Without | With | Δ | ||
case-01 | fail→pass | 5,072 | 5,717 | +13% | 1 | 1 | 0% | 844 | 2,232 | +164% | 0 | 0 | — |
case-02 | fail→pass | 8,049 | 4,742 | -41% | 1 | 1 | 0% | 1,418 | 2,061 | +45% | 0 | 0 | — |
case-03 | fail→pass | 10,169 | 4,455 | -56% | 1 | 1 | 0% | 1,842 | 2,078 | +13% | 0 | 0 | — |
case-04 | fail→pass | 7,696 | 2,658 | -65% | 1 | 1 | 0% | 1,261 | 1,685 | +34% | 0 | 0 | — |
case-05 | fail→pass | 13,424 | 2,524 | -81% | 1 | 1 | 0% | 2,127 | 1,629 | -23% | 0 | 0 | — |
case-06 | fail→pass | 7,211 | 1,939 | -73% | 1 | 1 | 0% | 1,146 | 1,551 | +35% | 0 | 0 | — |
case-07 | fail→pass | 10,353 | 1,958 | -81% | 1 | 1 | 0% | 1,726 | 1,517 | -12% | 0 | 0 | — |
case-08 | fail→pass | 4,848 | 4,572 | -6% | 1 | 1 | 0% | 677 | 1,962 | +190% | 0 | 0 | — |
case-09 | fail→pass | 19,461 | 17,975 | -8% | 1 | 1 | 0% | 3,460 | 4,454 | +29% | 0 | 0 | — |
case-10 | pass→pass | 9,773 | 10,394 | +6% | 1 | 1 | 0% | 1,654 | 3,069 | +86% | 0 | 0 | — |
case-15 | fail→pass | 9,569 | 2,521 | -74% | 1 | 1 | 0% | 1,457 | 1,610 | +11% | 0 | 0 | — |
case-11 | pass→pass | 10,141 | 10,051 | -1% | 1 | 1 | 0% | 1,762 | 3,029 | +72% | 0 | 0 | — |
case-12 | pass→pass | 5,744 | 9,602 | +67% | 1 | 1 | 0% | 938 | 2,861 | +205% | 0 | 0 | — |
case-13 | pass→pass | 9,328 | 10,043 | +8% | 1 | 1 | 0% | 1,435 | 2,862 | +99% | 0 | 0 | — |
case-14 | fail→pass | 20,073 | 2,733 | -86% | 1 | 1 | 0% | 1,216 | 1,745 | +44% | 0 | 0 | — |
case-16 | pass→pass | 19,265 | 12,624 | -34% | 1 | 1 | 0% | 2,852 | 3,369 | +18% | 0 | 0 | — |
case-17 | fail→pass | 6,855 | 5,424 | -21% | 1 | 1 | 0% | 968 | 2,177 | +125% | 0 | 0 | — |
case-18 | pass→pass | 6,115 | 4,428 | -28% | 1 | 1 | 0% | 953 | 1,999 | +110% | 0 | 0 | — |
case-19 | fail→fail | 13,156 | 21,104 | +60% | 1 | 1 | 0% | 2,628 | 5,449 | +107% | 0 | 0 | — |
case-20 | fail→fail | 6,003 | 7,766 | +29% | 1 | 1 | 0% | 937 | 2,386 | +155% | 0 | 0 | — |
case-21 | fail→fail | 20,852 | 24,205 | +16% | 1 | 1 | 0% | 4,403 | 6,542 | +49% | 0 | 0 | — |
case-22 | fail→fail | 20,243 | 23,873 | +18% | 1 | 1 | 0% | 3,935 | 6,231 | +58% | 0 | 0 | — |
DecimalAI ran this skill against gemini-3.6-flash twice over the same eval suite — once with the skill loaded and once without — and compared the two runs case by case. 22 cases were attempted, and 21 counted toward the lift figure. The other 1 produced results that are not comparable between the two arms, so they are excluded from the headline rather than averaged into it. The headline lift of +55 percentage points is the difference between those two pass rates over the 21 comparable cases.
Without the skill loaded, the model failed this case. With it loaded, the same prompt on the same model passed. This is one improved case from the latest verified run; every case, including any that regressed, is in the table above.
Other measured skills in the registry, with their headline benchmark lift.