kata-api-design-doc

Name: kata-api-design-doc
Availability: InStock
Author: Guardia

Generate structured Markdown REST API documentation from feature directives.

Updated Sep 3, 2025

Search Tags:#markdown #error handling #rest api #api documentation #endpoint design #idempotency-key #openapi complement

Ready to run

npx skills add https://github.com/guardiatechnology/design-system --skill kata-api-design-doc

💬 Prompt for ChatGPT / Claude Chat▼

Please help me install this Agent Skill.
Skill: kata-api-design-doc
Source: https://github.com/guardiatechnology/design-system/tree/main/.claude/skills/kata-api-design-doc
Command: npx skills add https://github.com/guardiatechnology/design-system --skill kata-api-design-doc

SYSTEM DOCUMENTATION & REQUIREMENTS

What problem does it solve?

It helps teams design consistent REST API endpoints and produce a human-readable, structured Markdown specification that complements the canonical OpenAPI artifact.

Core Features & Use Cases

Endpoint design from feature inputs: Converts a bounded-context feature description into concrete resources, operations, methods, and path patterns.
Conformance to REST and platform codexes: Aligns statuses, payload shapes, headers, pagination, sorting, idempotency, entity structures, error handling, and auth expectations.
On-demand Markdown documentation output: Generates a Markdown document saved under docs/{context}/oas/ with endpoint tables, global headers, known errors, and examples.

Quick Start

Ask the AI to generate the RESTful API Markdown documentation for your feature by providing the bounded context name, the feature description, and the base path you want to use.

Frequently Asked Questions about kata-api-design-doc

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

FAQPage Schema

How do I generate REST API documentation from feature requirements?▼

REST API documentation is generated by transforming feature directives into endpoint designs, payloads, headers, pagination, and error rules. This produces a structured Markdown file saved under docs/{context}/oas/.

What is the best way to design REST endpoints with consistent idempotency and error handling?▼

Designing REST endpoints with consistent idempotency and error handling requires aligning statuses, payload shapes, and headers with platform codexes. This ensures standardized auth behavior and idempotency-key rules across all operations.

Can I use Markdown documentation to complement my existing OpenAPI file?▼

Markdown documentation complements your existing OpenAPI file by providing a human-readable specification alongside the canonical artifact. It includes endpoint tables, global headers, known errors, and examples for bounded contexts.

How do I structure API payloads, pagination, and sorting rules for a new feature?▼

Structuring API payloads, pagination, and sorting rules involves converting feature descriptions into concrete resources and operations. The tool validates endpoint completeness and outputs standardized entity structures aligned with REST codexes.

Does this approach work for designing both public and private APIs?▼

This approach works for designing both public and private APIs within platform bounded contexts. It transforms feature directives into endpoint designs and generates human-readable Markdown documentation alongside the canonical OpenAPI file.