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.mdfrontend/.claude/skills/new-service/SKILL.md
GitHubnew-service
Workflow
- Confirm: name (kebab), endpoints and schema (
name:typepairs) as free text, then mocks as anAskUserQuestion:With mocks(Recommended) orWithout mocks. - Run from the repo root:
./.gaia/cli/gaia scaffold service <name> --endpoints "..." --schema "..." [--mocks]. It writes into the domain-layer folder underapp/services/, found as the one folder there besidesapi/(shipped asgaia/, often renamed to the company or API name). If it refuses because several folders qualify, ask which one withAskUserQuestion, one option per qualifying folder, and rerun with--layer <folder>. Flags and schema types:./.gaia/cli/gaia scaffold service --help. - Verify:
pnpm typecheckclean; if--mocks, run a single MSW round-trip in a vitest test. - 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; thenew-routeskill 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 truthfrontend/.claude/rules/api-service.md, quick pointer