Designs GraphQL schemas and resolvers that scale – domain-modeled types, Relay pagination, DataLoader batching to kill N+1, mutation payloads with typed user errors, and depth/complexity limits that stop abusive queries.
Designs GraphQL schemas and resolvers that scale - domain-modeled types, Relay pagination, DataLoader batching to kill N+1, mutation payloads with typed user errors, and depth/complexity limits that stop abusive queries. Use when someone asks "how should I structure this GraphQL type", "my resolvers are hammering the database", "cursor or offset pagination", "how do I version a GraphQL API", or is designing or reviewing a schema or federation split. Do NOT use for REST or RPC endpoint design - use api-design instead; do NOT use for the underlying table design - use database-schema instead; for hunting existing N+1s in a codebase, use n-plus-one-hunter.This is the skill's description: the text your AI reads to decide when the skill applies.
graphql-schema/SKILL.md
---
name: GraphQL Schema
description: Designs GraphQL schemas and resolvers that scale - domain-modeled types, Relay pagination, DataLoader batching to kill N+1, mutation payloads with typed user errors, and depth/complexity limits that stop abusive queries. Use when someone asks "how should I structure this GraphQL type", "my resolvers are hammering the database", "cursor or offset pagination", "how do I version a GraphQL API", or is designing or reviewing a schema or federation split. Do NOT use for REST or RPC endpoint design - use api-design instead; do NOT use for the underlying table design - use database-schema instead; for hunting existing N+1s in a codebase, use n-plus-one-hunter.
---
# GraphQL Schema
A GraphQL schema is a public contract that clients build against for years, and a resolver layer is an open invitation for N+1 queries and abusive nesting. This skill designs schemas clients love and servers survive: model the domain rather than the database, batch every relationship resolver, and put hard limits on what a single query may cost - because removing a shipped field or fixing a hot N+1 under load is 10x the effort of designing it right.
## Operating procedure
### Step 1: Gather inputs
- The domain nouns and the operations clients actually need (screens/use-cases, not tables).
- Largest list sizes and expected query shapes; who the clients are (first-party only vs public API - public means stricter limits).
- Data sources behind each type and which relationships cross a database or service boundary.
- Single graph or federated subgraphs.
### Step 2: Model the graph
1. Model around domain nouns, not database tables - the schema is for clients; the database is an implementation detail (table design belongs to database-schema).
2. Use schema-first SDL as the contract; generate types from it.
3. Prefer non-null (`!`) by default; make a field nullable only when null is a real, meaningful value or when the field's resolver can fail independently and you want partial results instead of a nulled-out parent chain.
4. Return rich object types, not scalars, so fields can grow without breaking clients.
5. Mutations return a payload type carrying the mutated entity and a `userErrors` list - do not model expected business failures as top-level GraphQL errors.Click to play with sound.