# Reviewing Api Spec > > - **Type:** Skill - **Install:** `agentstack add skill-bm629-agent-skills-reviewing-api-spec` - **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior - **Seller:** [bm629](https://agentstack.voostack.com/s/bm629) - **Installs:** 0 - **Category:** [Agent Skills](https://agentstack.voostack.com/c/agent-skills) - **Latest version:** 0.1.0 - **License:** MIT - **Upstream author:** [bm629](https://github.com/bm629) - **Source:** https://github.com/bm629/agent-skills/tree/main/skills/reviewing-api-spec ## Install ```sh agentstack add skill-bm629-agent-skills-reviewing-api-spec ``` Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent. ## About # `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.)* 12. **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](https://github.com/bm629) - **Source:** [bm629/agent-skills](https://github.com/bm629/agent-skills) - **License:** MIT Install and usage instructions live in the source repository linked above. ## Pricing - **Free** — Free ## Security capabilities Automated source analysis of v0.1.0 — what this tool can access: - **Network access:** no - **Filesystem access:** no - **Shell / process execution:** no - **Environment & secrets:** no - **Dynamic code execution:** no *"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.* ## Versions - **0.1.0** — security scan: passed — Imported from the upstream source. ## Links - Listing page: https://agentstack.voostack.com/l/skill-bm629-agent-skills-reviewing-api-spec - Seller: https://agentstack.voostack.com/s/bm629 - Browse the marketplace: https://agentstack.voostack.com/browse --- Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.