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.

Quality

70%

Does it follow best practices?

Run evals on this skill

Adds up to 20 points to the overall score

View guide

Securityby

—

The risk profile of this skill

Fix and improve this skill with Tessl

tessl review fix ./engineering/skills/api-design-reviewer/SKILL.md

Quality

Content

52%Weight 40%Scale 1-5

Reviews the quality of instructions and guidance provided to agents. Good implementation is clear, handles edge cases, and produces reliable results.

The skill's tooling and review flow are genuinely actionable with executable commands and validation gates, but the body is padded with reference-style REST material Claude already knows and fails to offload it to the provided reference files. Navigation between SKILL.md and the references/ bundle is effectively missing.

Suggestions

Move the REST reference sections (naming conventions, pagination, error formats, auth, HATEOAS, idempotency, backward compatibility, OpenAPI validation) into references/rest_design_rules.md and references/api_antipatterns.md, leaving only a concise overview plus 'See [references/rest_design_rules.md]' links in SKILL.md.

Add explicit links to references/api_antipatterns.md and references/rest_design_rules.md from the relevant body sections so the existing bundle files are surfaced rather than buried.

Trim the explanatory prose for HTTP methods, status codes, and pagination shapes to only the non-obvious conventions Claude would not already know, improving token efficiency.

Dimension	Reasoning	Score
Conciseness	The ~430-line body extensively explains REST concepts Claude already knows (HTTP method semantics, pagination JSON shapes, error/auth/HATEOAS/idempotency patterns, status-code meanings), which is noticeable padding beyond the actionable tool guidance.	2 / 5
Actionability	The Quick Start gives copy-paste executable commands with concrete flags (e.g. 'python3 scripts/api_linter.py openapi.json --format json -o lint.json') plus CI/CD and pre-commit examples, with only minor gaps in full per-tool usage.	4 / 5
Workflow Clarity	A clear sequenced review flow with explicit gates ('re-run until the linter is clean', '--exit-on-breaking passes', 'scorecard meets the agreed --min-grade') provides a fix-and-rerun feedback loop, though it is stated in prose rather than as an explicit per-failure branching checklist.	4 / 5
Progressive Disclosure	The body inlines ~300 lines of REST design reference material (naming, pagination, error formats, auth, HATEOAS, backward compatibility) that belongs in the existing reference files, and never links to references/api_antipatterns.md or references/rest_design_rules.md, leaving those bundle files buried.	2 / 5
	Total	12 / 20 Passed

Description

87%Weight 40%Scale 1-5

Based on the skill's description, can an agent find and select it at the right time? Clear, specific descriptions lead to better discovery.

The description is strong: it states concrete capabilities and gives explicit, natural 'Use when...' trigger guidance covering PR review, migration audits, and standard-setting. It is concise, third-person, and clearly distinct from neighboring skills.

Dimension	Reasoning	Score
Specificity	Names three concrete capabilities ('automated linting, breaking-change detection, and design scorecards') plus what they catch ('inconsistent conventions, missing versioning, and design smells'), giving several specific actions with only minor coverage gaps.	4 / 5
Completeness	It explicitly answers both what (REST API design review with linting, breaking-change detection, scorecards) and when (the 'Use when...' clause with concrete triggers), matching the level-5 anchor.	5 / 5
Trigger Term Quality	Natural trigger phrases like 'reviewing a PR that adds or changes API endpoints', 'auditing an existing API for v2 migration', and 'establishing API standards for a team' map well to what a user would say, with only a few synonyms missing.	4 / 5
Distinctiveness Conflict Risk	The REST API design-review niche with PR-review and v2-migration triggers is clearly distinct from other skills and carries minimal conflict risk.	5 / 5
	Total	18 / 20 Passed

Validation

100%

Warnings & errors only

Checks the skill against the spec for correct structure and formatting. All validation checks must pass before discovery and implementation can be scored.

Validation — 16 / 16 Passed

Validation for skill structure

No warnings or errors.

Repository: alirezarezvani/claude-skills
Path: engineering/skills/api-design-reviewer/SKILL.md
Commit: 19392f7

Reviewed: ~3 hours ago

Table of Contents

Discovery Implementation Validation

Is this your skill?

If you maintain this skill, you can claim it as your own. Once claimed, you can manage eval scenarios, bundle related skills, attach documentation or rules, and ensure cross-agent compatibility.