API Designer

What it does

API Designer translates feature requirements written in plain English into a complete, ready-to-implement API contract. For REST APIs it produces a valid OpenAPI 3.0 YAML document with path definitions, request body schemas, response codes, authentication headers, and error model definitions. For GraphQL it generates a full SDL schema with type definitions, queries, mutations, and subscriptions.

Beyond the contract, the skill generates paired example curl requests and JSON responses for each endpoint, plus a minimal implementation skeleton in your target language (Express, FastAPI, Go net/http, or Spring Boot). It enforces REST conventions by default: noun-based resource paths, plural collections, consistent 4xx error envelopes, and cursor-based pagination on list endpoints.

How to install

npx skills add user/api-designer

How to use

Describe what your API needs to do in plain language:

# REST · Node.js / Express
Design an API for a task management app.
Users can create projects, add tasks to projects,
assign tasks to team members, and mark tasks complete.
Include authentication via Bearer token.

Example partial output (OpenAPI 3.0):

openapi: "3.0.3"
info:
  title: Task Management API
  version: "1.0.0"

paths:
  /projects:
    get:
      summary: List all projects for authenticated user
      parameters:
        - name: cursor
          in: query
          schema:
            type: string
    post:
      summary: Create a new project
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ProjectCreate'

  # ... /projects/{id}/tasks, /tasks/{id}, etc.

Output artifacts

• OpenAPI 3.0 YAML — importable into Swagger UI, Postman, or Stoplight
• Example curl snippets — one per endpoint with realistic payload
• Implementation skeleton — route stubs with TODO comments
• Error model — standardized RFC 7807 problem detail responses