From f58cffd4d7758e33bc75e1035fdbae4ec6e2eb5c Mon Sep 17 00:00:00 2001 From: Julian Lechner Date: Thu, 24 Sep 2026 19:11:38 +0200 Subject: [PATCH] docs(skill): clarify API review triggers --- shared/skills/reviews/api-review/SKILL.md | 17 ++++++++++++++--- 1 file changed, 14 insertions(+), 3 deletions(-) diff --git a/shared/skills/reviews/api-review/SKILL.md b/shared/skills/reviews/api-review/SKILL.md index f82d242..9ccf501 100644 --- a/shared/skills/reviews/api-review/SKILL.md +++ b/shared/skills/reviews/api-review/SKILL.md @@ -1,10 +1,21 @@ --- name: api-review -description: Review API changes for compatibility and contract clarity. +description: Use when reviewing HTTP or RPC endpoint, request handling, serialization, schema, or API contract changes for correctness, security, and client compatibility. --- # API Review -Inspect request and response contracts, validation, errors, authorization, compatibility, and documentation. +Use when reviewing an HTTP or RPC API contract, endpoint, serializer, or request-handling change. -Return concrete findings and affected consumers. Keep detailed API standards for future customization. +## Review + +- Trace the request from routing through authentication, authorization, validation, business logic, and persistence. Check tenant or resource ownership at the point data is accessed. +- Compare request and response schemas, status codes, error shapes, pagination, identifiers, and nullability with existing consumers and published contracts. +- Check malformed, missing, oversized, duplicated, and unauthorized input where relevant. Ensure validation errors do not disclose sensitive data. +- Consider compatibility for older clients, retries, idempotency, concurrency, and versioning when those affect the endpoint. +- Review serialization defaults, content types, limits, and generated client or schema updates. +- Confirm documentation and examples match actual behavior. + +## Findings + +Report concrete contract breaks, security weaknesses, or incorrect behavior first. Give location, triggering request, impact on consumers, and a practical correction. Distinguish optional design suggestions from defects.