reviewing-api-reference — SKILL.md

Variant: standard · When to use: judging a finished (or amended) published API reference as an acceptance gate — checking a client developer can integrate from it and that it stays consistent with the handed-in api-spec contract, then emitting VERDICT: approve|revise with actionable findings.

Overview

This skill is the review half of an authoring/judging api-reference pair. Loaded by a reviewer who holds a finished, published API reference — the consumer-facing documentation an integrating client developer reads to call an API (getting-started, authentication, a per-endpoint reference, events/webhooks, shared object types, pagination, errors + rate-limits, code samples, an API changelog) — it judges that document against one question: can a client developer authenticate, make a first call, and integrate every operation from this reference alone, and does every documented endpoint, shape, and error trace to the upstream api-spec contract — no drift, nothing fabricated? It applies a fixed 11-condition usability + contract-consistency checklist — the same bar an api-reference author produces to, 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 reference; it judges and returns findings, and the producer revises.

The single most load-bearing check is api-spec-consistency (cond. 5): the reference is downstream of the engineering api-spec wire contract, and the reviewer spot-checks the documented endpoints, parameters, shapes, and errors against the handed-in api-spec. Drift or a fabricated/orphan endpoint is the highest-impact defect class.

When to activate

• A finished, published API reference needs an accept/revise decision before it ships to integrating developers.
• You are the independent reviewer / gate for an API reference a producer just authored, and you have the upstream api-spec to check consistency against.
• Re-judging a revised API reference after a prior revise verdict.
• Judging an amendment of an existing reference (a delta after the upstream contract changed) — the delta-scoped path (cond. 11).

Do NOT activate when: