reviewing-api-spec — SKILL.md

Variant: standard · When to use: judging a finished api-spec document as an acceptance gate — checking a client can call every operation and a server can implement it from the contract alone, then emitting VERDICT: approve|revise with actionable findings. Greenfield, or an amend (delta-scoped).

Overview

This skill is the review half of a producing/judging api-spec pair. Loaded by a reviewer who holds a finished api-spec document — the engineering wire contract of an API surface (operations, request + response schemas, auth, the error model, pagination/rate-limits, versioning, examples) — it judges that doc against one question: can a client engineer call every operation correctly and a server engineer implement it, from this document alone, with no ambiguity about shapes, errors, or auth? It applies a fixed 11-condition contract-completeness checklist — the same bar an api-spec author produces to (authoring-api-spec's Step-7 self-check), so the produce-bar and the review-bar do not drift — then emits a single machine-parseable verdict plus findings the author can act on in one revision pass. It is an acceptance gate — it does not author, fix, or rewrite the contract; it judges and returns findings, and the producer revises.

The bar is single-sourced with the author. The author's techniques — the style notation (OpenAPI / GraphQL SDL / proto), the named RFC conventions (RFC 9457, RFC 8594/9745, AIP-180/185), JSON-Schema fluency — are aids the reviewer judges by OUTCOME (is every operation typed both sides? is there one consistent error shape with every failure case named? do the examples match the schemas?), never conditions to demand. But note the boundary: the complete error model (cond-5), type-both-sides (cond-3), and per-operation authorization (cond-4) ARE real, load-bearing conditions for an api-spec — this IS the wire contract, so do NOT under-review them as "implementation detail." What stays an aid is the technique (a named notation/RFC), not the outcome (a typed operation, a complete error catalog, a per-operation scope).

Style-agnostic (load-bearing). The contract may be REST (OpenAPI/JSON-Schema), GraphQL (SDL + the errors array + nullability), or RPC/gRPC (proto + google.rpc.Status). Judge each in its own idiom: a GraphQL contract legitimately has no HTTP status codes (errors travel in the errors array; the typed payload-or-errors is the response), and a gRPC contract uses google.rpc.Status + the canonical codes, not HTTP. Demanding REST/OpenAPI idioms of a non-REST contract is the cardinal OpenAPI-reflex false-revise — do not do it. The style-agnostic guard threads cond-2 (operations), cond-3 (typed both sides), and cond-5 (error model): judge those in whatever style the contract uses.

When to activate

• A finished api-spec doc needs an accept/revise decision before a client integrates or a server implements.
• You are the independent reviewer / gate for an api-spec a producer just authored.
• Re-judging a revised api-spec after a prior revise verdict.
• Reviewing an amend — an approved contract + a change request — as a delta-scoped review (cond-11).