home / skills / velcrafting / codex-skills / client-generation

client-generation skill

safe

This skill generates and updates typed API clients from canonical contracts to ensure type-safe, deterministic integration across languages.

npx playbooks add skill velcrafting/codex-skills --skill client-generation

Review the files below or copy the command above to add this skill to your agents.

Files (1)

SKILL.md

1.3 KB

---
name: client-generation
description: Generate or update typed API clients from canonical contracts.
metadata:
  short-description: Typed API clients
  layer: api
  mode: write
  idempotent: true
---

# Skill: api/client-generation

## Purpose
Produce or refresh API clients so consumers:
- use typed, validated calls
- stay aligned with contracts
- do not hand-roll request logic

---

## Inputs
- Canonical API contract source
- Target language(s) or framework(s)
- Repo profile (preferred): `<repo>/REPO_PROFILE.json`

---

## Outputs
- Generated client code OR
- Updated handwritten client wrappers (repo standard)
- Regenerated artifacts committed if repo policy allows

---

## Non-goals
- Changing API behavior
- Writing UI or domain logic
- Editing generated code manually

---

## Workflow
1) Identify contract source and generator/tooling.
2) Regenerate clients deterministically.
3) Update import paths or version pins if needed.
4) Verify consumers compile/typecheck.

---

## Checks
- Generated clients compile
- No manual edits inside generated output
- Consumers pass typecheck

---

## Failure modes
- Generator output unstable → pin version or snapshot output.
- Contract invalid → block and return to `api/contract-update`.

---

## Telemetry
Log:
- skill: `api/client-generation`
- languages
- artifacts_written
- outcome

Overview

This skill generates or updates typed API clients from canonical API contracts so consumers call services with validated, type-safe interfaces. It automates deterministic regeneration, keeps clients aligned with contract changes, and minimizes hand-rolled request logic. Outputs can be new client libraries or updated wrapper layers following repo conventions.

How this skill works

The skill locates the canonical contract source and chosen generator/tooling for the target language or framework. It runs deterministic regeneration, updates imports or version pins as required, and optionally commits regenerated artifacts when repository policy allows. After generation it verifies compilation or typechecking of both the generated clients and their consumers to ensure correctness.

When to use it

When an API contract changes and clients must stay synchronized.
On CI to regenerate clients for multiple target languages after contract validation.
When introducing a new target language or framework for API consumption.
To replace hand-written request logic with type-safe, validated clients.
Before releasing a version that depends on updated API types or endpoints.

Best practices

Pin generator and tooling versions or snapshot outputs to ensure deterministic artifacts.
Store a repo profile describing language targets and repo conventions for consistent output.
Keep generated code isolated from manual edits; provide wrapper extension points for custom logic.
Run compile/typecheck in CI and block merges when consumers fail to typecheck.
Validate the canonical contract before generation and fail fast on contract errors.

Example use cases

Regenerate Python and TypeScript clients after an OpenAPI contract update and verify consumers compile.
Add a new language client (e.g., Go) by applying the repo profile and running the generation pipeline.
Replace brittle hand-rolled HTTP helpers with generated, typed clients to reduce runtime errors.
Automate client updates in CI so PRs that change contracts include deterministic client artifacts.

FAQ

What happens if the generator output is unstable?

Pin the generator version or snapshot generated outputs to a committed baseline. Treat instability as a failure mode and block merges until resolved.

Will this skill modify business logic or UI code?

No. It only produces or updates client artifacts and wrapper layers; it does not change API behavior, domain logic, or UI code.