From formal-specification
Designs contract-first REST APIs using OpenAPI 3.1 specifications, covering schemas, paths, parameters, responses, security, and best practices.
How this skill is triggered — by the user, by Claude, or both
Slash command
/formal-specification:openapi-designThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Use this skill when:
Use this skill when:
Before creating OpenAPI specifications:
docs-management skill for API design patternsRequirements → OpenAPI Spec → Review → Generate → Implement → Test
↑ ↓
←←←←←←←←←←←←← Iterate as needed ←←←←←←←←←←←←←←←←←←←←←←
openapi: 3.1.0
info:
title: API Title
version: 1.0.0
description: API description
servers:
- url: https://api.example.com/v1
description: Production
tags:
- name: Orders
description: Order management
paths:
# Define endpoints - see paths-definition.md
components:
schemas: { }
securitySchemes: { }
responses: { }
parameters: { }
For complete template: See paths-definition.md
| Method | Purpose | Idempotent |
|---|---|---|
| GET | Retrieve resource(s) | Yes |
| POST | Create resource | No |
| PUT | Replace resource | Yes |
| PATCH | Partial update | No |
| DELETE | Remove resource | Yes |
| Code | Use For |
|---|---|
| 200 | Successful GET, PUT, PATCH |
| 201 | Resource created (POST) |
| 204 | Successful DELETE |
| 400 | Malformed request |
| 401 | Authentication required |
| 404 | Resource not found |
| 422 | Validation error |
For complete guidance: See design-best-practices.md
Load on-demand based on need:
| Reference | Load When |
|---|---|
| paths-definition.md | Defining REST endpoints, operations, parameters |
| components-definition.md | Creating schemas, responses, security schemes |
| design-best-practices.md | Reviewing naming, status codes, versioning |
| Phase | Skill | Plugin | Purpose |
|---|---|---|---|
| DESIGN | openapi-design (this skill) | formal-specification | Architecture research, pattern selection |
| AUTHORING | openapi-authoring | spec-driven-development | Concrete YAML file creation |
| GOVERNANCE | contract-first-design | spec-driven-development | API governance, code generation |
Workflow: Design (research patterns) → Author (create YAML) → Govern (enforce contracts)
For current OpenAPI patterns and tools:
perplexity: "OpenAPI 3.1 specification" "REST API design patterns"
context7: "openapi" (for official documentation)
ref: "OpenAPI spec examples" "JSON Schema patterns"
Last Updated: 2026-01-17
npx claudepluginhub melodic-software/claude-code-plugins --plugin formal-specificationAuthors and validates OpenAPI 3.1 specifications for REST API design following API-first and contract-first practices. Provides templates for paths, components, servers, and responses.
Generates and maintains OpenAPI 3.1 specs from code, design-first approaches, or validation patterns for RESTful APIs, docs, SDKs, and contract compliance.
Structures OpenAPI 3.x specs with consistent naming, reusable schemas, error modeling, pagination, security schemes, and examples to produce a spec that works as a contract for code generation.