skills.rest
viditparashar96
viditparashar96COMMUNITY
Explore all skills by this author →
GitHub

eng-api-design

Review REST, GraphQL, and gRPC API designs and generate OpenAPI specifications.

Updated Apr 14, 2026
Search Tags:#documentation#openapi#rest#breaking-changes#contract-first#api-design#api-review
One-click install
npx skills add https://github.com/viditparashar96/second-brain-claude --skill eng-api-design
Or copy as Structured Prompt for Agent▼
Please help me install this Agent Skill.
Skill: eng-api-design
Source: https://github.com/viditparashar96/second-brain-claude/tree/main/skills/eng-api-design
Command: npx skills add https://github.com/viditparashar96/second-brain-claude --skill eng-api-design

SYSTEM DOCUMENTATION & REQUIREMENTS

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.

Frequently Asked Questions about eng-api-design

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
How do I detect breaking changes in a REST API?▼

Detect breaking changes in a REST API by running an automated design review against your OpenAPI specification. The review flags incompatibilities in endpoint changes and outputs a migration plan to help you evolve services safely.

What is contract-first API design?▼

Contract-first API design is a workflow where you derive resource models from product context and generate an OpenAPI specification before implementation. This eliminates ambiguity and regressions by enforcing the contract early in the development cycle.

How do I generate an OpenAPI v3 spec from a domain model?▼

Generate an OpenAPI v3 spec by applying an API design review to your product domain model. The process validates naming, HTTP methods, and security, saving the canonical specification to your local docs/api-specs directory.

Can I review GraphQL and gRPC contracts or just REST APIs?▼

You can review GraphQL and gRPC contracts as well as REST APIs. The review validates design changes, enforces contract-first workflows, and produces consistent documentation across all three protocols.

What is the best way to document API security and pagination?▼

The best way to document API security and pagination is to run an automated design review during endpoint creation. The review validates these constraints and generates a developer guide saved under docs/api-docs.

Does this API design workflow save canonical specs locally or to a registry?▼

This API design workflow saves canonical specs and developer guides locally. It writes OpenAPI files to docs/api-specs, creates guides in docs/api-docs, and records decisions to memory for auditability.

Related Skills

Explore More Software Engineering Skills→
ryan-nguyen-01ryan-nguyen-01
4

skill-api-openapi

Coordinate OpenAPI contract design and documentation across teams and services.

Community
Advanced
nashirabbashnashirabbash

api-documentation

Generate OpenAPI specs and interactive documentation for REST and GraphQL APIs.

Community
Intermediate
ccfccf

openapi-spec-generation

Generate and validate OpenAPI 3.1 specifications from design or code sources.

Community
Advanced
Sumeet138Sumeet138
1

openapi-spec-generation

Generate and validate OpenAPI 3.1 specifications from code and design inputs.

Community
Advanced