api-spec-builder — Turn a Prose Feature Description into OpenAPI YAML

mkdir -p ~/.claude/skills/api-spec-builder

New-Item -ItemType Directory -Force -Path "$env:USERPROFILE\.claude\skills\api-spec-builder" | Out-Null

---
name: api-spec-builder
description: Use this skill whenever the user describes an API feature in prose and wants the OpenAPI 3.1 YAML for it. Trigger on "write OpenAPI for…", "spec out an endpoint that…", "I need an API to…", "draft the schema for a search endpoint", "turn this requirement into OpenAPI". Do NOT use for generating server-side code from a spec, building a TypeScript SDK, or designing the database schema — those are downstream jobs handled by other skills.
version: 1.0.0
---

# api-spec-builder

Takes a prose feature description and produces a valid OpenAPI 3.1 YAML fragment ready to paste into the project's `openapi.yaml`.

## When invoked

If the prose is missing something obvious, ask ONE clarifying question covering all the gaps in a single turn. Do not Q&A-loop the user. Default to sensible REST conventions:

- Resource collections: `GET /resource`, `POST /resource`
- Single resource: `GET /resource/{id}`, `PATCH /resource/{id}`, `DELETE /resource/{id}`
- Sub-resources: `GET /resource/{id}/sub-resource`
- Search: `POST /resource/search` (not GET — search inputs grow beyond URL limits)
- Filters: query params for simple cases; POST body for complex
- Pagination: cursor-based (`cursor`, `limit`) — not page numbers
- Auth: `bearer` token via `Authorization` header

## Output structure

Always emit YAML with these sections in this order:

    paths:
      /your/endpoint:
        method:
          summary: …
          description: …
          tags: [resource]
          parameters:           # query/path/header
            - …
          requestBody:          # if applicable
            required: true
            content:
              application/json:
                schema:
                  $ref: '#/components/schemas/X'
          responses:
            '200': …
            '400': …
            '401': …
            '404': …            # if path has {id}
          security:
            - bearerAuth: []

    components:
      schemas:
        X:
          type: object
          required: […]
          properties: { … }
        Y: …
      responses:
        Error:                  # reusable error envelope
          description: …
          content: …
      securitySchemes:
        bearerAuth:
          type: http
          scheme: bearer

The fragment must be valid OpenAPI 3.1 (note: 3.1 uses JSON Schema 2020-12 — `nullable` is replaced by `type: [string, "null"]`).

## Schema rules

- Every property has a `description` (one short sentence) and an `example`.
- Strings have `minLength`/`maxLength` if there's any reasonable bound.
- Numbers have `minimum`/`maximum` where they exist.
- Enums use `enum:` with all valid values listed; do NOT make up values.
- IDs are strings (UUID or opaque), not integers, unless the user specifies otherwise.
- Timestamps are `string` with `format: date-time` (ISO 8601).
- Money is an object `{ amount_minor: integer, currency: string }`, not a float.

## Error responses

Always include a reusable `Error` response component with this shape and reference it from `400/401/404/409/422/500`:

    type: object
    required: [code, message]
    properties:
      code:    { type: string, example: invalid_argument }
      message: { type: string, example: "limit must be between 1 and 100" }
      details: { type: array, items: { type: object } }

Per-endpoint, only list the response codes that actually apply. Don't carpet-bomb every code.

## Example responses

Every `200` (and `201` where applicable) gets an `example` block under `content.application/json` with realistic-looking data — not "string", not "lorem ipsum". Make IDs look like real IDs, dates like real dates, money like real money. The example is the spec's most-read line; treat it as documentation.

## When NOT to use

- Generating server code → different skill (codegen)
- Building TypeScript/Python SDKs from the spec → SDK-gen skill
- Designing the database schema behind the API → data-model skill

## Output

Print the YAML in a single fenced code block. No preamble. If the user wants the file written to disk, they'll ask — default is paste-back.

/clear

Write the OpenAPI for an endpoint that lets a logged-in user
search their orders by date range, status (one of: pending,
shipped, delivered, cancelled), and an optional text query
on order notes. Return paginated results, max 50 per page.