API Design Reviewer — Development

The API Design Reviewer skill provides comprehensive analysis and review of REST API designs, focusing on conventions, best practices, and industry standards. It includes automated linting, breaking-change detection, and design scorecards to help teams build consistent, maintainable APIs.

engineering claude-code

📂 View skill on GitHub ↗ 🚀 How to use

✨ What it does

Lints OpenAPI/Swagger specs for naming conventions, HTTP method usage, URL structure, status code compliance, error form
Detects breaking changes between two API spec versions, including endpoint removal, response shape changes, field remova
Scores API design quality across consistency, documentation, security, usability, and performance, producing a letter gr
Provides guidance on REST design principles, versioning strategies, pagination patterns, error formats, authentication,
Includes scripts for CI/CD integration and pre-commit hooks.

🎯 When to use it

When reviewing a pull request that adds or changes API endpoints.
When auditing an existing API for a v2 migration.
When establishing API standards for a team.
When you need to detect breaking changes between API spec versions.
When you want to score the overall design quality of an API.

🚀 How to use

Trigger the skill by asking to review an API design or by running the provided scripts directly. The skill expects OpenAPI/Swagger spec files (JSON or YAML) as input. For breaking change detection, provide two spec versions. Example prompts:

Review the API design in openapi.json and report any issues.
Compare openapi-v1.json and openapi-v2.json for breaking changes.
Score the API design in openapi.json and give a grade.

Run the tools in order: linter, breaking change detector, scorecard. Fix issues and re-run until clean.

📄 Output: The skill produces lint reports, breaking change reports, and design scorecards (JSON output files) along with recommendations.

📦 Add this skill to Claude Code

# 1. Get the skills repo
git clone --depth 1 https://github.com/alirezarezvani/claude-skills /tmp/claude-skills

# 2. Copy this skill into your project (or ~/.claude/skills for all projects)
mkdir -p .claude/skills
cp -r /tmp/claude-skills/engineering/skills/api-design-reviewer .claude/skills/api-design-reviewer

Skill source: engineering/skills/api-design-reviewer/SKILL.md

⚠️ Good to know

The skill requires OpenAPI/Swagger specification files as input; it does not analyze code or runtime behavior.

❓ FAQ

What does the api_linter.py script check?

It checks for compliance with REST conventions, including naming conventions, HTTP method usage, URL structure, status code usage, error response formats, and documentation coverage.

How does the breaking_change_detector.py script work?

It compares two API specification versions to identify breaking changes such as endpoint removal, field removal, type changes, and required field additions. It can exit with a non-zero code if breaking changes are found when using --exit-on-breaking.

What is the api_scorecard.py script used for?

It provides a comprehensive scoring of API design quality across multiple dimensions, producing a letter grade (A-F) and improvement recommendations. It can enforce a minimum grade with --min-grade.

🤖 Overview, features, install steps and FAQ were generated from the project's SKILL.md on Sep 4, 2026. Always check the original source before running commands.