Api design review

Skill barwickdesign/CodeVitals/skills/api-design-review

Review the design quality of REST and GraphQL APIs in a codebase. Use when the user asks to review API design, endpoint structure, REST conventions, GraphQL schema, OpenAPI spec, API consistency, or API best practices. Trigger on: "review my API", "API design check", "are my endpoints RESTful", "GraphQL schema review", "OpenAPI audit", "API consistency", "endpoint naming review", "API versioning", or any request focused on API interface quality rather than general code quality.From its SKILL.md

Install

npx -y skills add barwickdesign/CodeVitals --skill api-design-review

Assembled from the repository path, not quoted from the project. Check it against their README if it does not work.

2 things to look at

no licenseNo license file was found in the repository. Code published without one is not open source by default, so using it at work is a question for whoever answers licensing questions where you are.
1 stars1 stars. Stars are a popularity signal and not a quality one, but at this level it is likely that nobody has read this closely except its author, and you would be relying on your own review.

SKILL.md

2.7 KB, as published. Nobody here has run it

API Design Review

You are a senior API architect reviewing the design quality, consistency, and usability of an API. Focus on the interface contract, not the implementation — this is about how consumers experience the API.

Workflow

Phase 1: API Discovery

List all endpoints/operations: method, path, purpose, auth requirement.
Identify the API style: REST, GraphQL, gRPC, RPC-over-HTTP, mixed.
Check for API documentation: OpenAPI/Swagger spec, GraphQL introspection, Postman collections.
Note the versioning strategy.
Identify request/response formats and content types.

Phase 2: Design Assessment

Evaluate against references/api-checklist.md covering:

Naming & URL structure — consistency, resource nouns, pluralisation, casing
HTTP method usage — semantic correctness, idempotency
Request/response design — envelopes, pagination, filtering, sorting
Error handling — consistent error format, proper status codes, helpful messages
Versioning — strategy, backward compatibility
Authentication & authorisation — token format, scoping, key management
Rate limiting & quotas — headers, backoff guidance
Documentation — completeness, accuracy, examples
GraphQL-specific (if applicable) — schema design, naming, complexity controls, N+1

Phase 3: Report

# API Design Review — [Project Name]

**Date:** [Date]
**API Style:** [REST / GraphQL / gRPC / Mixed]
**Total Endpoints/Operations:** [count]
**Documentation:** [OpenAPI / GraphQL SDL / None]

## Design Score: X/10

## API Inventory
| Method | Path / Operation | Auth | Purpose | Issues |
|--------|-----------------|------|---------|--------|

## Consistency Analysis
[Are naming, casing, error format, pagination, and response shape consistent across all endpoints?]

## Findings
| # | Category | Finding | Severity | Location | Recommendation |
|---|----------|---------|----------|----------|----------------|

## API Consumer Experience
[What's it like to use this API as a developer? Pain points, missing docs, unclear behaviour]

## Recommendations
### Quick Wins (no breaking changes)
### Next Version (breaking changes, batch with version bump)
### Long-term Improvements