Reviewing Api Spec

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).

Do NOT activate when:

• Authoring or repairing an api-spec → use authoring-api-spec. This skill never writes the contract.
• Reviewing the data-model (the stored entities the wire DTOs reference — upstream, one-directional) or the feature-spec (what the features do — upstream) → those are their own documents with their own gates.
• Reviewing the published, consumer-facing api-reference (the prose end-user docs, often generated from this contract — downstream) → use reviewing-api-reference. This contract is that reference's source of truth, never the reverse.
• Reviewing the implementation / server code that fulfils the contract → this gate judges the design document, not code.
• Reviewing a generic / ad-hoc engineering design doc, RFC, ADR, spec, or plan → use design-review. This gate is for the doc-library api-spec artifact — identified authoritatively by the template: api-spec frontmatter; a # API Specification heading is a fallback signal only when frontmatter is absent.
• Checking template/section conformance → that is a template concern. This skill judges quality against the bar, not whether every heading is present.

Workflow

Step 1: Read the whole contract with fresh, independent eyes

Read the api-spec doc end to end as if encountering it for the first time. Your stance is a gatekeeper for the next step (a client integrating + a server implementing): a finding carries weight only when it shows the API cannot be called or implemented as designed. Keep the upstream feature-spec (+ data-model where given) at hand — cond-2/cond-6/cond-10 check the contract against them. Detect the API style first (REST / GraphQL / gRPC, possibly mixed) so you judge each in its own idiom. The input is the doc itself — the operation list + the per-operation schemas + the error catalog + the shared types + the auth section + the examples all live in it (template sections); no separate companion artifact is required. Is this an amend? If you were handed a change request / delta against an existing contract, run the delta-scoped path (cond-11 active; scope to the changed operations + their classification + the deprecation/ripple). On a greenfield first build no change request is present — cond-11 is n/a.

Step 2: Run the contract-completeness checklist — judge each condition

For each condition, decide pass or gap. A condition fails only on a real, named deficiency — "I'd have designed it differently" is not a gap. The conditions are the single-sourced bar; do not add private ones.

The capability-boundary checklist item (below) applies ONLY when a capability_record was injected into the authoring invocation and is available as review context. When absent, treat it as n/a — do not penalise a document for lacking capability-boundary markers when no boundary was defined.

1. Style, base & versioning. The API style, base URL/endpoint, and a concrete versioning scheme are present; the breaking-vs-non-breaking change rule + the deprecation→sunset policy are stated. Gap on a missing versioning scheme, or no breaking-change rule / no deprecation policy. (Collapse: a v1 greenfield API states the policy even if nothing is deprecated yet. Non-collapsing baseline — style + base + a versioning scheme are present at any size.)
2. Every operation listed & traced. The operation list is complete + scannable; each operation maps to an upstream feature-spec behavior (no orphan/invented endpoint, none missing); the method + success-status semantics are correct (a mutating GET, or 200 where 201 belongs, is a gap). Gap on an operation with no trace (an invented endpoint), a feature-spec behavior with no operation, or a wrong method/status. (Judged against the upstreams given — an absent feature-spec is never itself a revise trigger.)
3. Every operation fully typed on both sides. Request + response fully typed, each field required/optional with constraints, every response keyed to a status code (REST) / a typed payload-or-errors (GraphQL) / a typed response message (gRPC). Gap on an untyped/unconstrained field, or a response with no status/typed body. A happy-path-only operation (only its 2xx) fails. (Part of the signature spine; non-collapsing baseline — every operation is typed both sides at any size.)
4. Auth & per-operation authorization. The authentication scheme(s) + credential location named; the OAuth flow chosen per client type; every non-public operation names its required scope/role (mapped to the op list); token lifecycle + HTTPS + no-secret-in-a-URL. Gap on an operation with no stated authorization (silently open or "logged-in" with no scope), an unnamed scheme, or a credential in a URL. (Collapse: an all-public API has no per-op scopes — but the scheme/transport are still stated.)
5. Error model complete. One consistent error shape for the whole API (a machine code + a message + a request/trace id), AND every named failure case enumerated per operation (validation/401/403/404/409/429/5xx as applicable) with its status + code + retryability. Gap on an operation showing only its 2xx, an ad-hoc/different error body per endpoint, a missing machine code/request id, or no retryability. The signature condition — the one that most differentiates this from generic design-review. (Non-collapsing baseline — the error model is not just the happy path at any size; a read-only op still names its 401/404.)
6. Shared types defined once + referenced; reference-not-redefine the data-model. Reusable DTOs defined once and referenced (no inline re-typing/drift); wire DTOs reference the data-model + note the deltas, never restate/contradict it. Gap on the same shape re-typed inline across operations (drift risk), or a DTO that re-types & contradicts a handed-in data-model. (Part of the signature spine. Greenfield clause: no data-model handed in → the DTO stands alone, not a gap.)
7. Pagination, filtering, sorting & rate-limits. Collection operations define pagination (strategy + envelope + default/max page size); filterable/sortable fields + a stable tie-breaker; rate limits + headers + 429. Gap on an unpaginated/unbounded collection, a sorted-paginated collection with no tie-breaker, or a missing max page size. (Collapse: a non-collection / single-resource API has no pagination — never false-revise it for "no pagination".)
8. Examples present + consistent. ≥1 worked request/response pair per primary operation, consistent with the schemas (same field names, types, status codes, error shape). Gap on an example with a field the schema lacks, a wrong type, a wrong status, or an error body that isn't the shared shape. (The api-spec analog of diagram⇄tables sync. Collapse: examples for the primary operations, not necessarily every one.)
9. Naming + versioning consistent. The naming convention + the versioning scheme are applied uniformly across the surface (no operation deviating). Gap on inconsistent naming/casing or a versioning scheme applied unevenly. (Scoped to surface-uniformity — distinct from cond-1's presence of the policy and cond-2's per-operation correctness; do not re-litigate those here.)
10. Grounded, honest & consistent. Operations/shapes/limits/codes reflect the feature-spec + data-model (not invented/boilerplate); assumptions explicit (thin-input → a blocker, not an invented shape); no fabrication; one-directional vs the api-reference (this contract is the published reference's source of truth — not reverse-engineered from the api-reference); references the data-model (one-directional, upstream); consistent with the shipped API where one exists (claims about current operations/shapes verified file:line, marked unverified where unconfirmable). Gap on an invented field/limit/status/code, an operation reverse-engineered from the published reference, or a documented operation that contradicts the deployed surface. (Non-collapsing baselines — no-fabrication + one-directional hold at any size. Greenfield clause: a brand-new/proposed/fictional API has no shipped surface → the consistency check is N/A, never a false-revise.)
11. (Amend only) delta is well-scoped, classified, ripple-clean, versioned. When reviewing a change against an existing contract: the changed operations meet conditions 1–10 on what they touched; the change is classified additive/breaking; a breaking change carries a new version + the deprecation→sunset plan + a migration guide (not an in-place edit under the same version); backward/forward compatibility analyzed; the forward/downward ripple flagged (the downstream api-reference re-sync, the impl/test-plan, the live clients); the doc version bumped + a changelog present; retired operations marked deprecated, not silently deleted. Gap on an un-scoped delta, a breaking change mis-classified as additive (or edited in place under the same version), an un-flagged ripple, or a silent deletion. (Collapse: on a greenfield first build this condition is n/a — do NOT full-re-review an unchanged contract, and do NOT demand a changelog on a first draft.)

1. Capability boundary (n/a when no capability_record): all entry_points reachable as API operations; publishes/consumes events have corresponding async operations; refs fields marked read-only cross-capability.

Proportionality. "Callable + implementable" scales with the API. A thin API legitimately collapses what it does not need — one operation → a short list; no collections → no pagination; an all-public read API → no per-op scopes; a greenfield contract → no shipped API to verify against; a first draft → no changelog. Judge completeness of the contract decisions, not word count or template-section presence. A small, complete contract that satisfies every applicable condition passes. Do not manufacture a gap from brevity.

Step 3: Decide the verdict

• approve — every applicable condition passes. A client can call every operation and a server can implement it from the contract alone, with no ambiguity about shapes, errors, or auth. Approve even if you can imagine stylistic improvements; the bar is callability + implementability, not perfection.
• revise — one or more conditions have a real, named gap that blocks calling or implementing (a happy-path-only operation, an untyped field, an inconsistent/missing error catalog, an example that contradicts its schema, a DTO that contradicts the data-model, an operation with no authorization, a breaking change edited in place, an un-scoped amend, etc.).

Do not revise to signal effort or to request nice-to-haves. A condition is either met or it isn't.

Step 4: Emit the verdict + actionable findings

Emit the verdict as a single line — the literal text VERDICT: approve or VERDICT: revise, on its own line, with no surrounding code fences, quotes, or extra words (the fences here are illustration only):

VERDICT: approve

Then, on the following lines, list findings. On revise, every finding is actionable — the failed condition, the exact location, and how to fix it — so the author can resolve it in one pass. On approve, findings are optional non-blocking notes.

A good finding names the gap and the fix:

> revise — Error model complete (cond. 5), §3 GET /invoices: the operation documents only its 200 response — no error cases. Fix: enumerate its failure cases (401 unauthorized, 403 forbidden if scoped, 404 not_found) in the shared Problem-Details shape with each status + machine code + retryability, so a client can handle every outcome.

A bad finding is vague and unactionable:

> The error handling could be more complete. (Which operation? Which errors? In what shape?)

Rules

Hard rules (never violate):

• Emit exactly one verdict line, VERDICT: approve or VERDICT: revise — that literal token, on its own line, nothing else on it. Downstream tooling parses it.
• Judge, never author. Return findings; do not rewrite, fix, or fill in the contract. The producer revises.
• Single-sourced bar. Judge against the twelve conditions in Step 2 — the same bar the author (authoring-api-spec's Step-7 self-check) produces to. Do not invent extra conditions or apply a stricter private standard.
• Aids are judged by outcome, never demanded. The style notation (OpenAPI/SDL/proto), the named RFCs (9457/8594/9745/AIP), JSON-Schema fluency are the author's techniques — judge whether the operation is typed / the error catalog is

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: bm629
• Source: bm629/agent-skills
• License: MIT

Install and usage instructions live in the source repository linked above.