api-spec-writer

Generate OpenAPI 3.0/3.1 YAML contracts with endpoints, schemas, and security definitions.

Updated May 9, 2026

Search Tags:#openapi #yaml #pagination #api contract #rfc 7807 #rest design #security schemes

Ready to run

npx skills add https://github.com/GustavoGutierrez/engineering-skills --skill api-spec-writer

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: api-spec-writer
Source: https://github.com/GustavoGutierrez/engineering-skills/tree/main/skills/api-spec-writer
Command: npx skills add https://github.com/GustavoGutierrez/engineering-skills --skill api-spec-writer

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

It solves the problem of turning API requirements and domain models into a complete, consistent, and machine-valid API contract.

Core Features & Use Cases

Design complete OpenAPI contracts: Generates OpenAPI 3.0/3.1 YAML including endpoints, schemas, security, pagination, and error handling.
Standardize API quality: Enforces RESTful semantics, RFC 7807 Problem Details errors, schema reuse via components, and OpenAPI structural validity checks.
Support contract evidence: Includes request/response examples for major success and error cases to make the spec testable and understandable.

Quick Start

Use the api-spec-writer skill to generate an OpenAPI 3.1 YAML contract for a REST API described by your endpoint requirements and data models.

Frequently Asked Questions about api-spec-writer

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

FAQPage Schema

How do I generate an OpenAPI 3.1 YAML contract from domain models and endpoint requirements?▼

To generate an OpenAPI YAML contract, provide your domain models and endpoint requirements to produce valid OpenAPI 3.0/3.1 YAML with endpoints, schemas, security definitions, and pagination patterns. It enforces strict REST semantics and component-based schema reuse.

What is the best way to standardize REST API error handling using RFC 7807?▼

Standardizing REST API error handling with RFC 7807 involves generating OpenAPI contracts that enforce Problem Details error payloads. This ensures consistent, machine-valid error responses across all API endpoints while maintaining strict structural validity.

Can I add new endpoints to an existing OpenAPI contract without breaking schema reuse?▼

Adding endpoints to existing OpenAPI contracts maintains schema reuse by applying component-based definitions and strong typing. It supports partial endpoint additions while enforcing unique operationIds and structural validity checks to prevent integration breaking.

Does OpenAPI 3.1 support built-in pagination patterns for REST API design?▼

OpenAPI 3.1 supports pagination patterns for REST API design by generating contracts that include standardized pagination definitions within the YAML structure. This ensures consistent data retrieval behaviors across endpoint collections.

What security schemes are enforced when designing REST API contracts with OpenAPI?▼

Designing REST API contracts with OpenAPI enforces explicit security schemes and security definitions within the YAML output. This ensures protected endpoints are properly configured according to strict REST semantics and contract requirements.