Skip to main content Home Creators curiositech some_claude_skills openapi-spec-writer
openapi-spec-writer Expert in writing OpenAPI 3.0/3.1 specifications for REST APIs. Specializes in schema design, documentation best practices, API-first development, and tooling integration. Generates comprehensive API documentation that serves as both documentation and contract.
Jump to install Skills Marketplace Discover and explore AI skills built by the community.
Install with Codex or Claude Copy this prompt, paste it into Codex, Claude, or another assistant, and let it review the skill page and install it for you.
Show prompt details A direct command skips the review prompt. Inspect the source before running it.
npx skills add https://github.com/curiositech/some_claude_skills --skill openapi-spec-writerThe command stays on one line. Scroll horizontally to inspect it before copying.
Prefer a local copy? Download the files currently available to SkillsMP.
Download Zip Downloading... More from this repository Working type director's reference for selecting, pairing, and shipping typefaces with real taste. Covers a broad, opinionated catalog of typefaces and foundries (libre through commercial), a mood/era/register-driven selection framework that never collapses to one answer, font pairing as logic, fluid type scales, variable-font axes (incl. opsz/GRAD), OpenType features, web-font performance (subsetting, font-display, size-adjust fallback metrics), and licensing literacy (SIL OFL vs commercial EULA, desktop/web/app, trials). Explicitly retires the overused AI-design defaults (Inter, Roboto, Montserrat, Poppins, Fraunces, Geist, Söhne, the Fontshare/ITF starter pack) and names fresher alternatives in every role. Use for font selection, pairing, type scales, web-font optimization, variable fonts, OpenType, and typographic systems. NOT for logo/wordmark design, icon fonts, general CSS, or image-based/raster typography.
Multi-agent coordination daemon for coding agents. Use for deterministic port claims, session tracking, salvage, file claims, notes, pub/sub, tuple-space coordination, background fleets, and debugging multi-agent failures across Claude Code, Codex, Gemini CLI, Cursor, or Windsurf. NOT for production deploy orchestration, Docker or Kubernetes networking, or cloud service discovery.
Use this skill when running SEO audits, optimizing for AI search engines (AI Overviews, ChatGPT, Perplexity), generating schema markup, diagnosing traffic drops, fixing Core Web Vitals, managing site migrations, or building keyword strategies. Runs scored full-site audits (0-100 Health Score) across 21 modules including technical SEO, E-E-A-T, hreflang, and programmatic SEO. Three modes: Audit, Plan, Execute. NOT for PPC/Ads, social media management, or generic marketing strategy unrelated to organic search.
Related occupations SOC
Based on SOC occupation classification
name openapi-spec-writer description Expert in writing OpenAPI 3.0/3.1 specifications for REST APIs. Specializes in schema design, documentation best practices, API-first development, and tooling integration. Generates comprehensive API documentation that serves as both documentation and contract. version 1.0.0 metadata {"category":"documentation","tags":["openapi","swagger","api-documentation","rest","api-design"],"pairs-with":[{"skill":"api-architect","reason":"API design decisions are formalized and documented through OpenAPI specifications"},{"skill":"rest-api-design","reason":"REST endpoint design and OpenAPI documentation are tightly coupled deliverables"},{"skill":"technical-writer","reason":"API documentation quality depends on technical writing clarity and completeness"}]}
OpenAPI Spec Writer
Overview
Expert in writing OpenAPI 3.0/3.1 specifications for REST APIs. Specializes in schema design, documentation best practices, API-first development, and tooling integration. Generates comprehensive API documentation that serves as both documentation and contract.
When to Use
Creating OpenAPI specifications for new APIs
Documenting existing REST APIs
Designing API contracts before implementation
Generating client SDKs from specs
Setting up interactive API documentation (Swagger UI, Redoc)
Validating API responses against schemas
Migrating from OpenAPI 2.0 (Swagger) to 3.x
Capabilities
Specification Writing
OpenAPI 3.0 and 3.1 syntax
Path and operation definitions
Request/response schemas
Authentication schemes
Server configurations
Schema Design
JSON Schema with OpenAPI extensions
Reusable component schemas
Discriminators for polymorphism
oneOf, anyOf, allOf composition
Nullable types and defaults
Documentation Quality
Meaningful descriptions and examples
Markdown in descriptions
Request/response examples
Error response documentation
Deprecation notices
Tooling Integration
Swagger UI configuration
Redoc customization
Spectral linting rules
SDK generation setup
Mock server configuration
Dependencies
Works well with:
api-architect - API design patternsrest-api-design - RESTful conventionstypescript-pro - Generated client typesgithub-actions-pipeline-builder - CI validation
Examples
Complete OpenAPI 3.1 Spec
openapi: 3.1 .0
info:
title: Task Management API
description: |
RESTful API for managing tasks and projects.
All endpoints require a Bearer token in the Authorization header.
- 1000 requests per hour per API key
- Rate limit headers included in all responses
version: 1.0 .0
contact:
name: API Support
email: api@example.com
url: https://docs.example.com
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: Polymorphic Schemas (Discriminator)
components:
schemas:
Notification:
type: object
required:
- id
- type
- created_at
discriminator:
propertyName: type
mapping:
email: '#/components/schemas/EmailNotification'
sms: '#/components/schemas/SmsNotification'
push: '#/components/schemas/PushNotification'
properties:
id:
type: string
format: uuid
type:
type: string
enum: [email , sms , push ]
created_at:
type: string
format: date-time
EmailNotification:
allOf:
- $ref: '#/components/schemas/Notification'
- type: object
required:
- to
- subject
Spectral Linting Rules
extends: ["spectral:oas" ]
rules:
operation-operationId: error
operation-description: error
oas3-schema-description: warn
path-casing:
given: "$.paths[*]~"
then:
function: casing
functionOptions:
type: kebab
operation-security-defined: error
operation-success-response: error
require-examples:
message: "Responses should have examples"
given: "$.paths.*.*.responses.*.content.*.schema"
then:
field: example
function: truthy
Best Practices
Use components - Extract reusable schemas, parameters, responsesProvide examples - Real-world examples for every schemaMeaningful descriptions - Markdown-formatted, explain business contextConsistent naming - kebab-case paths, camelCase propertiesVersion your API - Include version in URL or headerDocument errors - Define all error responses with examplesUse operationId - Unique, descriptive IDs for SDK generationValidate with linting - Use Spectral to enforce standardsKeep spec in sync - Automate validation in CI
Common Pitfalls
Missing required fields - Forgetting to mark fields as requiredInconsistent naming - Mixing snake_case and camelCaseGeneric descriptions - "Returns data" instead of specific detailsNo examples - Makes spec hard to understandOutdated spec - Spec doesn't match implementationOverusing anyOf - Makes schemas hard to understandMissing error responses - Only documenting happy pathNo pagination - List endpoints without pagination info https://api.example.com/v1
description:
Production
server
-
url:
https://staging-api.example.com/v1
description:
Staging
server
-
url:
http://localhost:3000/v1
description:
Local
development
tags:
-
name:
Tasks
description:
Task
management
operations
-
name:
Projects
description:
Project
management
operations
paths:
/tasks:
get:
operationId:
listTasks
summary:
List
all
tasks
description:
Returns
a
paginated
list
of
tasks
with
optional
filtering.
tags:
-
Tasks
parameters:
-
$ref:
'#/components/parameters/PageParam'
-
$ref:
'#/components/parameters/LimitParam'
-
name:
status
in:
query
description:
Filter
by
task
status
schema:
$ref:
'#/components/schemas/TaskStatus'
-
name:
project_id
in:
query
description:
Filter
by
project
ID
schema:
type:
string
format:
uuid
responses:
'200':
description:
Successful
response
content:
application/json:
schema:
$ref:
'#/components/schemas/TaskListResponse'
examples:
default:
$ref:
'#/components/examples/TaskListExample'
headers:
X-Total-Count:
schema:
type:
integer
description:
Total
number
of
tasks
matching
the
query
'400':
$ref:
'#/components/responses/BadRequest'
'401':
$ref:
'#/components/responses/Unauthorized'
post:
operationId:
createTask
summary:
Create
a
new
task
description:
Creates
a
new
task
and
returns
the
created
resource.
tags:
-
Tasks
requestBody:
required:
true
content:
application/json:
schema:
$ref:
'#/components/schemas/CreateTaskRequest'
examples:
minimal:
summary:
Minimal
task
value:
title:
"Complete documentation"
full:
summary:
Full
task
with
all
fields
value:
title:
"Complete documentation"
description:
"Write API docs for v1.0"
project_id:
"550e8400-e29b-41d4-a716-446655440000"
due_date:
"2024-12-31"
priority:
"high"
responses:
'201':
description:
Task
created
successfully
content:
application/json:
schema:
$ref:
'#/components/schemas/Task'
headers:
Location:
schema:
type:
string
format:
uri
description:
URL
of
the
created
resource
'400':
$ref:
'#/components/responses/BadRequest'
'401':
$ref:
'#/components/responses/Unauthorized'
'422':
$ref:
'#/components/responses/ValidationError'
/tasks/{taskId}:
parameters:
-
$ref:
'#/components/parameters/TaskIdParam'
get:
operationId:
getTask
summary:
Get
a
task
by
ID
tags:
-
Tasks
responses:
'200':
description:
Successful
response
content:
application/json:
schema:
$ref:
'#/components/schemas/Task'
'404':
$ref:
'#/components/responses/NotFound'
patch:
operationId:
updateTask
summary:
Update
a
task
description:
Partially
updates
a
task.
Only
provided
fields
are
updated.
tags:
-
Tasks
requestBody:
required:
true
content:
application/json:
schema:
$ref:
'#/components/schemas/UpdateTaskRequest'
responses:
'200':
description:
Task
updated
successfully
content:
application/json:
schema:
$ref:
'#/components/schemas/Task'
'404':
$ref:
'#/components/responses/NotFound'
'422':
$ref:
'#/components/responses/ValidationError'
delete:
operationId:
deleteTask
summary:
Delete
a
task
tags:
-
Tasks
responses:
'204':
description:
Task
deleted
successfully
'404':
$ref:
'#/components/responses/NotFound'
components:
securitySchemes:
bearerAuth:
type:
http
scheme:
bearer
bearerFormat:
JWT
description:
JWT
token
obtained
from
/auth/login
parameters:
TaskIdParam:
name:
taskId
in:
path
required:
true
description:
Unique
task
identifier
schema:
type:
string
format:
uuid
example:
"550e8400-e29b-41d4-a716-446655440000"
PageParam:
name:
page
in:
query
description:
Page
number
for
pagination
(1-indexed)
schema:
type:
integer
minimum:
1
default:
1
LimitParam:
name:
limit
in:
query
description:
Number
of
items
per
page
schema:
type:
integer
minimum:
1
maximum:
100
default:
20
schemas:
Task:
type:
object
required:
-
id
-
title
-
status
-
created_at
-
updated_at
properties:
id:
type:
string
format:
uuid
description:
Unique
identifier
readOnly:
true
title:
type:
string
minLength:
1
maxLength:
200
description:
Task
title
description:
type:
string
maxLength:
5000
description:
Detailed
task
description
(supports
Markdown)
status:
$ref:
'#/components/schemas/TaskStatus'
priority:
$ref:
'#/components/schemas/Priority'
project_id:
type:
string
format:
uuid
description:
Associated
project
ID
due_date:
type:
string
format:
date
description:
Due
date
(ISO
8601
)
created_at:
type:
string
format:
date-time
readOnly:
true
updated_at:
type:
string
format:
date-time
readOnly:
true
TaskStatus:
type:
string
enum:
-
pending
-
in_progress
-
completed
-
cancelled
description:
Current
task
status
default:
pending
Priority:
type:
string
enum:
-
low
-
medium
-
high
-
urgent
default:
medium
CreateTaskRequest:
type:
object
required:
-
title
properties:
title:
type:
string
minLength:
1
maxLength:
200
description:
type:
string
maxLength:
5000
project_id:
type:
string
format:
uuid
due_date:
type:
string
format:
date
priority:
$ref:
'#/components/schemas/Priority'
UpdateTaskRequest:
type:
object
minProperties:
1
properties:
title:
type:
string
minLength:
1
maxLength:
200
description:
type:
string
maxLength:
5000
status:
$ref:
'#/components/schemas/TaskStatus'
priority:
$ref:
'#/components/schemas/Priority'
due_date:
type:
string
format:
date
TaskListResponse:
type:
object
required:
-
data
-
pagination
properties:
data:
type:
array
items:
$ref:
'#/components/schemas/Task'
pagination:
$ref:
'#/components/schemas/Pagination'
Pagination:
type:
object
required:
-
page
-
limit
-
total
-
total_pages
properties:
page:
type:
integer
limit:
type:
integer
total:
type:
integer
total_pages:
type:
integer
has_next:
type:
boolean
has_prev:
type:
boolean
Error:
type:
object
required:
-
code
-
message
properties:
code:
type:
string
description:
Machine-readable
error
code
message:
type:
string
description:
Human-readable
error
message
details:
type:
object
additionalProperties:
true
description:
Additional
error
details
ValidationError:
allOf:
-
$ref:
'#/components/schemas/Error'
-
type:
object
properties:
errors:
type:
array
items:
type:
object
properties:
field:
type:
string
message:
type:
string
responses:
BadRequest:
description:
Bad
request
-
invalid
parameters
content:
application/json:
schema:
$ref:
'#/components/schemas/Error'
example:
code:
"BAD_REQUEST"
message:
"Invalid query parameters"
Unauthorized:
description:
Authentication
required
content:
application/json:
schema:
$ref:
'#/components/schemas/Error'
example:
code:
"UNAUTHORIZED"
message:
"Invalid or expired token"
NotFound:
description:
Resource
not
found
content:
application/json:
schema:
$ref:
'#/components/schemas/Error'
example:
code:
"NOT_FOUND"
message:
"Task not found"
ValidationError:
description:
Validation
failed
content:
application/json:
schema:
$ref:
'#/components/schemas/ValidationError'
example:
code:
"VALIDATION_ERROR"
message:
"Request validation failed"
errors:
-
field:
"title"
message:
"Title is required"
examples:
TaskListExample:
value:
data:
-
id:
"550e8400-e29b-41d4-a716-446655440000"
title:
"Complete documentation"
status:
"in_progress"
priority:
"high"
created_at:
"2024-01-15T10:30:00Z"
updated_at:
"2024-01-15T10:30:00Z"
pagination:
page:
1
limit:
20
total:
42
total_pages:
3
has_next:
true
has_prev:
false
security:
-
bearerAuth:
properties:
to:
type:
string
format:
email
subject:
type:
string
body:
type:
string
SmsNotification:
allOf:
-
$ref:
'#/components/schemas/Notification'
-
type:
object
required:
-
phone_number
-
message
properties:
phone_number:
type:
string
pattern:
'^\+[1-9]\d{1,14}$'
message:
type:
string
maxLength:
160
