skills.rest
devCharuzu
devCharuzuCOMMUNITY
Explore all skills by this author →
GitHub

api-design-reviewer

Lint OpenAPI specs for REST conventions and breaking changes.

Updated Apr 16, 2026
Search Tags:#design#api#openapi#rest#lint#breaking-changes#scorecard
One-click install
npx skills add https://github.com/devCharuzu/philfida-taskmanage --skill api-design-reviewer-devcharuzu
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-reviewer
Source: https://github.com/devCharuzu/philfida-taskmanage/tree/main/.windsurf/skills/api-design-reviewer
Command: npx skills add https://github.com/devCharuzu/philfida-taskmanage --skill api-design-reviewer-devcharuzu

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes scripts (resource) and references (resource) components.

What problem does it solve?

API design teams often face inconsistent API designs, undocumented endpoints, and risky changes that break clients. This skill provides automated tooling to lint API specs, detect breaking changes, and score design quality to improve consistency and safety.

Core Features & Use Cases

  • API Linting and Convention Analysis: enforces resource naming, HTTP method usage, URL structure, status codes, and error formats.
  • Breaking Change Detection: tracks endpoint removals, response shape changes, and new required fields across versions.
  • API Design Scoring: multi-dimensional scorecard evaluating consistency, documentation, security, usability, and performance.
  • Use Case: teams iterating on a public REST API can continuously lint specs, compare versions, and receive actionable improvements.

Quick Start

Run the API Design Reviewer against your OpenAPI specification to produce a lint report, a breaking-change diff, and a scorecard.

Frequently Asked Questions about api-design-reviewer

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I lint an OpenAPI spec to enforce REST conventions?▼

Breaking change detection in OpenAPI tracks endpoint removals, response shape changes, and new required fields across versions. Comparing multiple API versions reveals risky modifications that could break existing clients.

Can I score API design quality across multiple dimensions?▼

API design scoring evaluates consistency, documentation, security, usability, and performance through a weighted scorecard. This multi-dimensional evaluation produces actionable reports highlighting areas needing improvement across API versions.

Does this API review work with raw endpoint definitions or only OpenAPI specs?▼

The API review processes both OpenAPI specifications and raw endpoint definitions. It analyzes either input format to lint naming conventions, detect breaking changes, and score overall design quality across versions.

What is the best way to automate API design reviews for continuous iteration?▼

Automating API design reviews involves running continuous linting, version comparisons, and quality scoring against your API specs. This produces lint reports, breaking-change diffs, and scorecards to guide iterative improvements for public REST APIs.

What limitations exist when detecting breaking changes in REST APIs?▼

Breaking change detection focuses on endpoint removals, response shape changes, and new required fields across versions. It analyzes OpenAPI specs and raw definitions, but complex semantic behavior changes may require additional manual review beyond automated linting.

Related Skills

Explore More Software Engineering Skills→
mikopbxmikopbx
569

openapi-analyzer

Extract and analyze OpenAPI 3.1.0 specifications to validate endpoints and generate tests.

Official
Advanced
wesleyosantos91wesleyosantos91
6

commit-message

Generate Conventional Commits messages from git diffs with type and scope.

Community
Basic
superluminar-iosuperluminar-io
10

api-mock-server

Generate HTTP and gRPC mock servers and clients from pinky-promise API specs.

Official
Intermediate
mosheshammoshesham

api-design-reviewer

Lint OpenAPI specs for REST conventions and detect breaking changes.

Community
Advanced