skills.rest
bm629
bm629COMMUNITY
Explore all skills by this author →
GitHub

reviewing-api-spec

Reviews finished API specification documents against an 11-condition contract-completeness checklist and emits an approve or revise verdict.

1|1|Updated May 24, 2026
Search Tags:#openapi#graphql#contract review#grpc#api specification#acceptance gate#error model
One-click install
npx skills add https://github.com/bm629/agent-skills --skill reviewing-api-spec-bm629
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: reviewing-api-spec
Source: https://github.com/bm629/agent-skills/tree/main/skills/reviewing-api-spec
Command: npx skills add https://github.com/bm629/agent-skills --skill reviewing-api-spec-bm629

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve? Teams need an independent acceptance gate that decides whether a finished API specification is complete enough for a client to call every operation and a server to implement it, without the author grading their own work. ## Core Features & Use Cases - Contract-completeness review: Judges an api-spec against a fixed 11-condition bar covering operations, typed request/response schemas, auth, error model, pagination, versioning, and examples. - Style-agnostic judging: Evaluates REST, GraphQL, and gRPC contracts in their own idiom, avoiding false rejections for missing HTTP status codes in non-REST styles. - Delta-scoped amend review: Reviews changes against an existing contract, checking additive/breaking classification, deprecation plans, and downstream ripple. - Use Case: After authoring an OpenAPI contract for a billing API, run this review to catch a happy-path-only operation missing its error cases before a client team integrates against it. ## Quick Start Use reviewing-api-spec on docs/specs/billing-api-spec.md and give me the verdict with actionable findings.

Frequently Asked Questions about reviewing-api-spec

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

FAQPage Schema
How do I review an API specification before implementation?▼

Run the review against the finished api-spec document, which is judged against an 11-condition checklist covering operations, typed schemas, auth, error model, pagination, and examples. The output is a single VERDICT: approve or VERDICT: revise line plus actionable findings.

What makes an API spec review different from a general design review?▼

An api-spec review checks whether a client can call every operation and a server can implement the contract from the document alone, using a fixed contract-completeness bar. Generic design review covers RFCs, ADRs, and plans without this wire-contract focus.

Does this review work for GraphQL or gRPC API contracts?▼

Yes, the review is style-agnostic and judges each contract in its own idiom. GraphQL contracts are evaluated on the errors array and nullability, gRPC on google.rpc.Status and proto messages, never penalized for lacking HTTP status codes or OpenAPI.

Can the review handle a change to an existing approved API contract?▼

Yes, amend reviews are delta-scoped: only the changed operations are re-judged, plus the additive/breaking classification, deprecation and sunset plan, migration guide, and downstream ripple. The unchanged contract is not re-reviewed.

When should I not use this API spec review?▼

Do not use it to author or repair a contract, review the data model or feature spec, review the published consumer-facing api-reference, or review server implementation code. It only judges the finished api-spec design document.

Related Skills

Explore More Software Engineering Skills→
spencerpaulyspencerpauly
672

adding-api-docs

Generate OpenAPI documentation from existing API routes and schemas.

Community
Intermediate
ali-masterali-master
8

oRPC Hey API Integration

Generate oRPC contracts from OpenAPI specifications or convert Hey API clients.

Community
Advanced
pedapudipedapudi
4

zicato-tune-scoring

Calibrate zicato scoring contracts and promotion gates for generation tournaments.

Community
Advanced
ranvirsinghranvirsingh

speckit-plan

Generate design notes, data-model hints, API contracts, and ADRs for GitHub Issues.

Community
Advanced