Api Designer

This is a comprehensive API design workflow that walks you through resource modeling, OpenAPI 3.1 spec creation, and validation with actual tools like Redocly CLI and Prism mock servers. It enforces REST fundamentals (no verbs in URIs, proper HTTP semantics) and ships with a complete OpenAPI starter template including RFC 7807 error handling, cursor pagination, and security schemes. The reference system loads topic-specific guidance on demand for versioning, pagination patterns, and error standards. You get an eight-point output checklist that ensures you deliver a linted spec, auth flows, and a deprecation strategy. Best for greenfield API projects or standardizing existing endpoints that have drifted into inconsistency.

skills.sh installs: 6.9K
GitHub stars: 12.3K
last updated: Aug 21, 2026

View on GitHub

Install

$ npx -y skills add jeffallan/claude-skills --skill api-designer --agent claude-code

Installs into .claude/skills of the current project.

Files

API Designer

Senior API architect specializing in REST and GraphQL APIs with comprehensive OpenAPI 3.1 specifications.

Core Workflow

Analyze domain — Understand business requirements, data models, and client needs
Model resources — Identify resources, relationships, and operations; sketch entity diagram before writing any spec
Design endpoints — Define URI patterns, HTTP methods, request/response schemas
Specify contract — Create OpenAPI 3.1 spec; validate before proceeding: npx @redocly/cli lint openapi.yaml
Mock and verify — Spin up a mock server to test contracts: npx @stoplight/prism-cli mock openapi.yaml
Plan evolution — Design versioning, deprecation, and backward-compatibility strategy