Skip to content
Back to skills

New Service

ASecurity

Scaffolds a new API service with request functions, Zod schemas, URL constants, optional TanStack Query options, and optional MSW mock handlers. Use this skill whenever the user asks to "add a service", "create the projects API", "wire up CRUD for users", or anything implying a new service folder under `app/services/` (`app/services/<layer>/{name}/`) with parsers/types/requests + matching `test/mocks/{name}/` collections.

  • 27 stars
  • 0 votes
  • 0 copies
  • 5 views
  • Added October 26, 2026
ai-agentsgoreactapibackend

Works with

  • cli
  • api

Security analysis

A100/100

Scanned November 11, 2026

npx -y skills add gaia-harness/gaia --skill new-service --agent claude-code

Installs into .claude/skills of the current project.

Are you the author of New Service?

Add the live security badge to your README. It updates with every re-scan.

Security grade badge for New Service
[![Security: A — Skills Directory](https://www.skillsdirectory.com/api/skills/gaia-harness-new-service/badge)](https://www.skillsdirectory.com/skills/gaia-harness-new-service)

More formats (shields.io, HTML) on the badges page. Keep it an A: scan every change in CI with Pro.

Download with Pro
SKILL.md
---
name: new-service
description: Scaffolds a new API service with request functions, Zod schemas, URL constants, optional TanStack Query options, and optional MSW mock handlers. Use this skill whenever the user asks to "add a service", "create the projects API", "wire up CRUD for users", or anything implying a new service folder under `app/services/` (`app/services/<layer>/{name}/`) with parsers/types/requests + matching `test/mocks/{name}/` collections.
model: haiku
---

# 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/`. 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 `apps/web/.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
- `apps/web/.claude/rules/api-service.md`, quick pointer

Attribution

Is this your skill, or is something wrong with this listing? Request removal or report an issue. Author removals are honored within 72 hours.

View all in ai-agents →

Comments

Loading comments…

Newsletter

Get the weekly list of safe new skills, and the ones we pulled.