eng-api-design

What problem does it solve?

This Skill eliminates ambiguity and regressions in API design by enforcing contract-first development, detecting breaking changes, and producing consistent, discoverable API documentation so engineering teams can evolve services safely.

Core Features & Use Cases

• Contract-first specification: derive resource models from product context and generate OpenAPI specs before implementation.
• Automated design reviews: naming, HTTP method/status correctness, security checks, pagination and performance guidance, and breaking-change detection with migration guidance.
• Local-first documentation & logging: save canonical specs to docs/api-specs, create developer guides in docs/api-docs, and record decisions to memory for auditability.
• Use Case: When modifying an existing public endpoint, run the review to detect incompatibilities, produce a migration plan, and output an updated OpenAPI file.

Quick Start

Run an API design review for the Payments product using the domain model in PRODUCTS.md, generate an OpenAPI v3 spec saved to docs/api-specs/payments-v1.yaml, and list any breaking changes and migration steps.