An API can look tidy in an OpenAPI file and still make every consumer guess what happens after a partial failure.

Why this Skill is needed

API Design Quality Review evaluates an API contract before implementation or versioning. It makes inputs, outputs, errors, permissions, lifecycle, and consumer impact explicit enough to test.

What the Skill does

Review supplied API designs before implementation or versioning. Build an operation-level matrix across resources and naming, request/response fields and boundaries, errors and HTTP status, authentication/authorization, idempotency and retry, pagination, rate limits, version evolution, consumer migration, privacy, and observability.

Bind each gap to an API-## finding with the operation, source and evidence, status, consumer impact and compatibility risk, owner and decision question, and validation method. One request/response example or OpenAPI file proves only that the artifact exists; it does not prove a complete or compatible contract.

Awesome QA Skills organizes Skills by language and testing stage; the series overview explains the shared installation model.

What it does not do

The Skill does not call an API, run security or performance tests, or approve a versioning policy. It will not infer missing fields, errors, permissions, retry rules, rate limits, or idempotency behavior from convention. Without runtime identity, time, environment, inputs, responses, and raw results, runtime status stays unverified or unassessed.

What it checks

Operation-level dimensionReview questionEvidence to retain
Resource and request/responseAre names, required fields, types, nullability, and boundaries explicit?Versioned schema and sourced examples
Error and statusAre business codes, HTTP status, and retry meanings defined per operation?Error catalog, operation exceptions, consumer behavior
Identity and effectsWho may call it, and what prevents duplicate or unauthorized writes?Authorization rule, idempotency/retry contract, state effects
Collection behaviorAre pagination, sort, filters, and rate limits specified?Contract source and consumer constraints
Evolution and migrationWhich old/new client-server combinations are supported, and how are consumers notified?Version policy, migration order, compatibility evidence
Privacy and observabilityWhat may appear in responses/logs, and how is one operation traced?Redaction and correlation rules

One sample cannot establish coverage for an operation. Record declared exceptions and consumer-specific constraints rather than assuming that one response applies everywhere.

Audit inputs before you start

Before analyzing Contract finding, classify the input into six evidence states. A gap is not automatically a failure, but it must not disappear inside the conclusion.

StateMeaningHow this Skill should handle it
knownDirectly supported by the supplied materialKeep the source, version, and time with the judgment
missingNeeded for this pass but not suppliedName the smallest evidence action and limit the conclusion
conflictingSources disagreeShow both sources and route the conflict to an owner
stalePresent but outside the relevant version or time windowMark freshness; old evidence is not current proof
out_of_scopeRelated but excluded from this passKeep the boundary explicit
assumptionsTemporarily adopted to continue analysisState how and when the assumption will be checked

Keep the input version, scope, environment, evidence locations, and accountable owner together. Without a run record, deliver analysis, design, or a validation plan—not an execution pass.

From problem to structured Finding

API-## finding contract

Every finding names a stable operation, source/evidence, status (assessed, missing, conflicting, stale, or unassessed), consumer/data/security impact and compatibility risk with a P0–P3 rationale, owner role and decision/migration question, and validation with preconditions, action, expected result, and raw evidence needed. Keep facts, inferences, recommendations, and Human decisions separate.

A complete case

This case follows Input, Analysis, Finding, Decision, and Validation. When material is incomplete, keep missing, conflicting, or assumptions visible instead of turning them into a pass.

Input

MaterialWhat to provideWhat to do when it is missing
Contract materialOpenAPI, request and response examples, status codes, and version policyList undefined fields instead of guessing
Consumer contextMobile, web, billing, retry behavior, and rollout orderName consumers that were not consulted
Risk boundaryAuthorization, idempotency, state transitions, and backward compatibilityLeave release approval to the owner

Use a request like this:


Use the api-design-quality-review Skill.

Task: review a subscription cancellation API before mobile, web, and billing consumers implement it
Inputs: [requirements, versions, links, logs, reports, or data paths]
Scope: [included and excluded objects]
Unknowns: [missing environment, accounts, data, or permissions]
Expected output: [risk-ordered findings, evidence status, and next actions]

Audit the inputs first. Separate facts, assumptions, and open questions. Do not claim execution without a run record.

Analysis

Start with a bounded pass—review a subscription cancellation API before mobile, web, and billing consumers implement it. For cancellation, define what happens when the subscription is already cancelled, the billing provider is unavailable, or the request is repeated. The contract should tell consumers whether to retry, poll, display a final state, or ask a human to intervene.

The useful handoff keeps the input version, time window, evidence index, owner, and next validation action together. The Skill can organize uncertainty; it cannot manufacture the missing artifact.

Finding

The following is a review candidate format, not an execution result:

FieldExample
ID / operationAPI-01 — POST /subscriptions/{id}/cancel
Source / statusSupplied cancellation design and version; missing until repeat-request and provider-failure behavior are specified
Impact / compatibility riskMobile, web, and billing consumers may make conflicting retry or final-state decisions; prioritize using project impact evidence
Owner / decisionAPI owner to confirm the repeated-cancel rule; consumer owners to confirm migration needs
ValidationOnce defined, review request/response and consumer examples; any runtime claim requires call identity, environment, inputs, outputs, logs, and raw results

Decision

The API owner decides the contract and version policy. Mobile, web, and billing owners supply their compatibility and migration constraints; the Skill surfaces those trade-offs but does not approve one.

Validation

Before implementation, validate that each affected operation has an applicable source, defined boundaries, consumer expectations, and a closeable decision. This is design evidence only; do not describe it as a compatibility or runtime test.

How a Finding enters the next stage

Handoff output

Output fieldWhy it existsExample status
Contract findingMissing, conflicting, stale, or unverifiable API ruleAPI-##, impact, and source
Consumer consequenceWhat client behavior becomes ambiguous or unsafeAffected consumer and version
Readiness actionField, error, policy, or migration decision to clarifyOwner and closure evidence

Do not write “passed” without a run record, query result, or source artifact. A good review walks through one consumer journey, one failure path, and one version change. It does not approve the design by counting endpoints.

Next-stage route

Route missing operation rules to the API owner, and migration questions to each affected consumer owner. Preserve the operation, version, evidence state, decision question, and compatibility risk in the handoff.

How to prepare better input

Provide the API objective, operations, OpenAPI or contract versions, request/response examples, all known consumers, authorization model, error and retry rules, pagination/rate limits, rollout order, and migration notes. Mark which consumers or versions have not been reviewed; do not let one example stand in for the rest.

Working with other Skills

Common traps

  1. Reviewing schemas without consumer journeys.
  2. Treating a 200 response as a complete success contract.
  3. Leaving version and retry behavior to implementation folklore.

Install and invoke

Install the individual Skill. The series overview carries the longer installation explanation.


npx skills add https://github.com/naodeng/awesome-qa-skills/tree/main/skills/en/testing-types/api-design-quality-review -g

After installation, invoke it with the api-design-quality-review Skill and attach the real project material.

FAQ

Can the review happen before code exists?

That is the point. It can identify unverifiable or conflicting contract choices before they become compatibility work.

Does the Skill choose the API version?

No. It exposes trade-offs and evidence gaps; the responsible owner makes the version decision.

The example above is a design and review pattern, not an execution result. Keep static analysis, runtime evidence, human approval, and release acceptance separate.

References

Source Skill and execution contract

The complete execution contract lives in the API Design Quality Review prompt. Read it before invoking the Skill; the prompt defines the detailed workflow and output contract. The source directory also contains the entry point and supporting assets where they exist.

The entry point centers operation contract, error model, authorization, idempotency, compatibility, and consumer impact. Read the supporting prompt before writing a conclusion, and keep the Skill’s decision boundary visible.

ACP (Agent Client Protocol)Active MemoryAgent AuthorizationAgent CardAgent Evals
Share