Skip to content
Hidden Logic Lab

Generate a typed API client from OpenAPI via a repo skill

Claude Code or Cursor follows a SKILL.md that regenerates a typed SDK from your OpenAPI spec, with usage examples and a diff checklist agents run every time the spec changes.

Claude Code, Cursor
·Coding·35 min·Working

A repeatable generate step, committed client output or generated folder policy, and example calls that compile against the new types.

  1. 1

    Pin the generator command in the skill

    The command in SKILL.md should match CI. Agents will improvise flags if the skill is vague.

  2. 2

    Commit spec and client together

    One PR should not merge a spec change without the regenerated client. Split only when the generator is broken and note it in the PR.

  3. 3

    Run the example through typecheck

    The usage example is the canary. If it does not compile, downstream app code will not either.

The prompt to paste

Write SKILL.md for keeping a typed API client in sync with our OpenAPI spec. Agents must not hand-write fetch wrappers when the spec is the source of truth.

Repository context:
[OpenAPI file path, generator tool if any e.g. openapi-typescript, orval, openapi-generator — or write [confirm generator]]
[output folder for client, package name, test command]

SKILL.md sections:
1. Purpose — regenerate client from spec; update call sites with types.
2. When to use — spec bump, new endpoint, breaking change release; when not to use — undocumented internal endpoints not in spec.
3. Required inputs: spec version or git sha, changelog excerpt if provided, and whether breaking changes are allowed this PR.
4. Steps:
   - Read the OpenAPI diff (or full spec if small) and list added/changed/removed operations.
   - Run generator command: [paste exact command or [confirm command]].
   - Fix compile errors in src/ call sites; do not cast to any to silence types.
   - Add or update one usage example file examples/<service>-client.ts showing auth header pattern we use.
   - Run typecheck and tests: [paste commands].
5. Generator config rules: pin version in package.json; no manual edits inside generated/ unless the repo already documents exceptions.
6. Two example prompts: patch version bump vs breaking major with migration notes.
7. Pitfalls: editing generated files by hand, stale spec in repo, missing error response types, duplicating DTOs in app code.
8. Done means: checklist — spec committed, client regenerated, typecheck green, example file runs or typechecks.

Also list a ## Human review block (outside SKILL.md): what reviewers should spot-check in the OpenAPI diff (auth, pagination, nullable fields).

Rules:
- Do not invent endpoint names not in the spec path you were given.
- Output SKILL.md only unless you add the short Human review block.

OpenAPI specs lie about optional fields. The skill should tell the agent to read response examples and existing call sites, not only the generated types.

Sample case written by Hidden Logic Lab. Not affiliated with Claude Code or Cursor.

More in Coding

Get new cases in your inbox

Weekly notes on new use cases and agent workflows. No product pitches.

Occasional notes on new cases. No product pitches in the first note.