API Design Quality Review
Use it to check whether operations, inputs/outputs, errors, permissions, and compatibility evolution are verifiable.
StatusStable
TypeAtomic Skill
DomainSoftware testing
SDLCTest design
Good forQA / DEV
LanguageChinese / English
EvalsEvals ✓
Synced2026-09-15
Why this Skill
It turns this Skill's method into a quality input that can be executed, reviewed, and reused.
- 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.
These are the Skill's expected output requirements, not evidence that it ran in a real project.
- 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
-gapi-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.