skills.rest
Patasse97
Patasse97COMMUNITY
Explore all skills by this author →
GitHub

api-design-reviewer

Audit OpenAPI/Swagger API designs for quality and consistency.

Updated Apr 9, 2026
Search Tags:#openapi#rest#lint#breaking-changes#analyze#api-design#scorecard
One-click install
npx skills add https://github.com/Patasse97/claude-skills --skill api-design-reviewer-patasse97
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: api-design-reviewer
Source: https://github.com/Patasse97/claude-skills/tree/main/engineering/api-design-reviewer
Command: npx skills add https://github.com/Patasse97/claude-skills --skill api-design-reviewer-patasse97

SYSTEM DOCUMENTATION & REQUIREMENTS

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

What problem does it solve?

API teams struggle to ensure API designs are consistent, well-documented, and future-proof across evolving specifications.

Core Features & Use Cases

  • API Linting and Convention Analysis: checks naming, URL structure, HTTP method usage, error formats, and documentation gaps.
  • Breaking Change Detection and Scoring: identifies endpoint removals, schema changes, and computes multi-may scorecards with recommendations.
  • Design Governance: produces a design scorecard and actionable guidance for API vendors, engineers, and product teams.

Quick Start

To begin, provide your OpenAPI/Swagger document to run automated linting, breaking-change detection, and scoring.

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 specification for REST convention violations?▼

You provide your OpenAPI or Swagger document to run automated linting checks on paths, operations, schemas, and responses. The review enforces RESTful conventions, parameter naming, versioning practices, and error formats.

How do I detect breaking changes in an evolving API design?▼

Breaking change detection identifies endpoint removals and schema modifications across evolving OpenAPI specifications. It analyzes these changes and computes a multi-layer scorecard with actionable recommendations for governance.

What is an API design scorecard and how does it help with governance?▼

An API design scorecard is a structured report generated by auditing OpenAPI specifications. It provides actionable guidance and consistency scores to help engineers and product teams enforce design governance across projects.

Can I analyze Swagger documents for security considerations and documentation gaps?▼

Yes, you can analyze Swagger documents to identify security considerations and documentation gaps. The audit checks URL structures, HTTP method usage, and schema definitions to output structured recommendations.

Does the API linter work with OpenAPI specifications across different teams and projects?▼

Yes, the linter applies to OpenAPI and Swagger specifications across multiple teams and projects. It enables consistent linting of operations and schemas, ensuring uniform API quality and future-proof designs.

Related Skills

Explore More Software Engineering Skills→
xlelibertyxleliberty

api-design-reviewer

Analyze OpenAPI and Swagger specifications for RESTful design compliance.

Community
Advanced
maltemdmaltemd

designing-content-governance-flows

Design content governance workflows for creation, review, approval, and publication.

Community
Advanced
sunholo-datasunholo-data
33

AILANG Release Manager

Automates end-to-end AILANG release management including pre-release checks, version bumps, changelog updates, git tagging, CI/CD verification, and release broadcasting.

Official
Intermediate
icartshicartsh
4

code-analyze

Analyze .NET solutions for code quality, security, and dependency issues.

Community
Advanced