Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standar
Install
Use withClaudeCursorCodex
The file stays in the publisher's repository. PlugMCP does not host or rewrite it.
Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.
name: api-designer
description: Use when designing REST or GraphQL APIs, creating OpenAPI specifications, or planning API architecture. Invoke for resource modeling, versioning strategies, pagination patterns, error handling standards.
license: MIT
metadata:
author: https://github.com/Jeffallan
company: https://synergetic.solutions
version: "1.1.0"
domain: api-architecture
triggers: API design, REST API, OpenAPI, API specification, API architecture, resource modeling, API versioning, GraphQL schema, API documentation
role: architect
scope: design
output-format: specification
related-skills: graphql-architect, fastapi-expert, nestjs-expert, spring-boot-engineer, security-reviewer
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
{
"type": "https://api.example.com/errors/validation-error",
"title": "Validation Error",
"status": 422,
"detail": "The 'email' field must be a valid email address.",
"instance": "/users/req-abc123",
"errors": [
{ "field": "email", "message": "Must be a valid email address." }
]
}
Always use Content-Type: application/problem+json for error responses.
type must be a stable, documented URI — never a generic string.
detail must be human-readable and actionable.
Extend with errors[] for field-level validation failures.
Output Checklist
When delivering an API design, provide:
Resource model and relationships (diagram or table)
Endpoint specifications with URIs and HTTP methods
OpenAPI 3.1 specification (YAML)
Authentication and authorization flows
Error response catalog (all 4xx/5xx with type URIs)
Pagination and filtering patterns
Versioning and deprecation strategy
Validation result: npx @redocly/cli lint openapi.yaml passes with no errors
Download skills/api-designer/SKILL.md from the publisher, or copy the path and open the repository. PlugMCP lists the skill and does not host the file.
Where does api-designer live?
The publisher keeps it at https://github.com/Jeffallan/claude-skills.
Which agents can use api-designer?
Claude, Cursor, and Codex can read a SKILL.md you add from the publisher's repository.