API Design Quality Review - QA Skill Library

Why this Skill

It turns this Skill's method into a quality input that can be executed, reviewed, and reused.

Use it to check whether operations, inputs/outputs, errors, permissions, and compatibility evolution are verifiable.
Do not execute an API or claim security, compatibility, or performance tests passed.
Do not infer all fields, errors, permissions, rate limits, idempotency, or version rules from one example.
Every API-## includes operation, source/evidence, impact, compatibility risk, owner role, decision question, and validation method.
Treating one successful response as a complete OpenAPI contract.

When to use

Use this Skill

Use it to check whether operations, inputs/outputs, errors, permissions, and compatibility evolution are verifiable.
Use it to find contract gaps across consumers, versions, or migration plans.
Use it when examples are incomplete, boundaries are undefined, or runtime evidence is missing.

Common pitfalls

Treating one successful response as a complete OpenAPI contract.
Checking status codes without error bodies, authorization, retry, idempotency, and consumer behavior.
Treating a document version or linter pass as compatibility-test evidence.

Input

Minimum Input

Read `prompts/api-design-quality-review.md` and audit objective, version, consumers, scope, and evidence.

Recommended Input

Project goal
Test scope
Constraints

Optional Context

Relevant code or configuration
Historical results
Logs and metrics

Output

The output follows this Skill's method and makes facts, assumptions, risks, and next steps explicit.

Judge the output value before installing

01Read prompts/api-design-quality-review.md and audit objective, version, consumers, scope, and evidence.
02Classify material as known, missing, conflicting, stale, out_of_scope, and assumptions.
03Build an operation/field coverage matrix and bind each gap to an API-##, source, evidence, impact, and validation method.
04Separate contract facts, evidence-backed inferences, recommendations, and Human decisions; state what compatibility, authorization, and error evidence is still needed.

View full output structure

05Deliver a bounded first pass when incomplete; a request/response example is not a complete contract.

How It Works

01Read prompts/api-design-quality-review.md and audit objective, version, consumers, scope, and evidence.
02Classify material as known, missing, conflicting, stale, out_of_scope, and assumptions.
03Build an operation/field coverage matrix and bind each gap to an API-##, source, evidence, impact, and validation method.
04Separate contract facts, evidence-backed inferences, recommendations, and Human decisions; state what compatibility, authorization, and error evidence is still needed.
05Deliver a bounded first pass when incomplete; a request/response example is not a complete contract.

Install & Quick Start

Install command / SHELL

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

api-design-quality-review.prompt

@skill api-design-quality-review

Using the current project context, produce an actionable result following this Skill.

Additional context:
[Paste project context or requirement]

---
name: api-design-quality-review
description: Use this skill when an API, OpenAPI, or consumer contract needs a quality review before implementation or versioning; triggers include API design review, contract readiness review, and consumer compatibility audit.
---

# API Design Quality Review

Review API designs, OpenAPI/contracts, request/response examples, error models, authorization, idempotency, pagination, status codes, version evolution, and consumer impact before implementation. It produces `API-##` findings and validation preparation; it does not execute an API or approve a final versioning policy.

## When to Use

- Use it to check whether operations, inputs/outputs, errors, permissions, and compatibility evolution are verifiable.
- Use it to find contract gaps across consumers, versions, or migration plans.
- Use it when examples are incomplete, boundaries are undefined, or runtime evidence is missing.

Do not use it to send requests, load-test, execute security tests, or choose a final API versioning policy for a team.

## Output Format Options

- Use Markdown by default; when a table, CSV, or JSON is requested, preserve the same evidence, status, impact, owner, and validation fields.
- Do not present a structured format or static inventory as execution, pass, approval, or release evidence.

## How to Use

1. Read this Skill's primary prompt and provide the objective, scope, material, environment, and available evidence.
2. Follow the prompt's input audit and output contract; deliver a bounded first pass when information is incomplete.
3. Retain source, evidence status, impact, owner role, close condition, and validation method for every finding.

## Workflow

1. Read `prompts/api-design-quality-review.md` and audit objective, version, consumers, scope, and evidence.
2. Classify material as `known`, `missing`, `conflicting`, `stale`, `out_of_scope`, and `assumptions`.
3. Build an operation/field coverage matrix and bind each gap to an `API-##`, source, evidence, impact, and validation method.
4. Separate contract facts, evidence-backed inferences, recommendations, and Human decisions; state what compatibility, authorization, and error evidence is still needed.
5. Deliver a bounded first pass when incomplete; a request/response example is not a complete contract.

## Core Constraints

- Do not execute an API or claim security, compatibility, or performance tests passed.
- Do not infer all fields, errors, permissions, rate limits, idempotency, or version rules from one example.
- Every `API-##` includes operation, source/evidence, impact, compatibility risk, owner role, decision question, and validation method.
- Without execution identity, time, environment, inputs, responses, and raw results, runtime status remains `unverified`, `unexecuted`, or `unassessed`.

## Reference Files

- Always read `prompts/api-design-quality-review.md` before producing a review.
- For regression, read `evals/eval.yaml` and its cases; structural validation is not API behavior evidence.
- For trigger checks, use `evals/trigger-prompts.csv` and `evals/local-rules.json`; missing selection trace is `BLOCKED`.

## Best Practices

- Prioritize high-impact gaps with a verifiable next action, using the smallest useful experiment or evidence request.
- Separate facts, evidence-backed inferences, recommendations, and Human decisions; never upgrade an assumption into a conclusion.

## Delivery Checklist

- [ ] Audit operations, versions, consumers, scope, and evidence.
- [ ] Check input/output, errors, authorization, idempotency, pagination, status, evolution, and migration impact.
- [ ] Give each `API-##` minimum evidence, impact, owner, and validation method.
- [ ] Separate examples/design claims from runtime evidence.
- [ ] Do not choose compatibility policy, risk acceptance, or release approval for a Human.

## Common Pitfalls

- Treating one successful response as a complete OpenAPI contract.
- Checking status codes without error bodies, authorization, retry, idempotency, and consumer behavior.
- Treating a document version or linter pass as compatibility-test evidence.