new-service

Scaffold a new API service with request functions, Zod schemas, URL constants, and optional MSW mock handlers. Use this skill whenever the user asks to "add a service", "create the projects API", "wir

SKILL.md

GitHub

new-service

Workflow

  1. Confirm: name (kebab), endpoints and schema (name:type pairs) as free text, then mocks as an AskUserQuestion: With mocks (Recommended) or Without mocks.
  2. Run from the repo root: ./.gaia/cli/gaia scaffold service <name> --endpoints "..." --schema "..." [--mocks]. It writes into the domain-layer folder under app/services/, found as the one folder there besides api/ (shipped as gaia/, often renamed to the company or API name). If it refuses because several folders qualify, ask which one with AskUserQuestion, one option per qualifying folder, and rerun with --layer <folder>. Flags and schema types: ./.gaia/cli/gaia scaffold service --help.
  3. Verify: pnpm typecheck clean; if --mocks, run a single MSW round-trip in a vitest test.
  4. Wire the service into the consuming route and page. Which data-loading variant applies is the rule in frontend/.claude/skills/react-code/SKILL.md; the new-route skill scaffolds a route bound to the service. Before wiring by hand, read how an existing service is wired and follow that pattern.

Query options

When @tanstack/react-query is installed and the service has get, the scaffold also writes queries.ts (query keys and queryOptions factories over the request functions). To add it to an existing service, run ./.gaia/cli/gaia scaffold service <name> --queries-only [--layer <folder>]; it writes only queries.ts and refuses when Query is not installed. Turn Query on with ./.gaia/cli/gaia init configure-data-layer --query true.

A new API domain

A backend with its own base URL or casing needs its own create() instance. Ask the backend's casing first with AskUserQuestion: camelCase (Recommended) or snake_case. Then create app/services/<new-layer>/api.ts modelled on the shipped layer's api.ts, passing create({isSnakeCaseEnabled: true}) for a snake_case backend, and scaffold with --layer <new-layer>; the scaffolder reads that flag to pick the mock data's key casing.

For an SDK-client backend (Supabase, Firebase), the Ky layer stays in place for any REST domain. An SDK-backed domain's request functions wrap the SDK's calls instead of api, and the data-loading rule applies unchanged.

The clientLoader and Query variants suit unauthenticated or cookie-authenticated APIs; a token or secret never goes into the root-loader ENV.

See

  • wiki/concepts/API Service Pattern.md, pattern source of truth
  • frontend/.claude/rules/api-service.md, quick pointer