graphql

name	graphql
description	GraphQL — schema, resolvers, N+1/DataLoader, pagination.

GraphQL

Detection Signals

Load this skill when any of the following are present:

Signal	Location
graphql or @graphql-tools/* dependency	package.json
.graphql / .gql schema files	anywhere in the repository
apollo-server, graphql-yoga, mercurius	package.json
strawberry-graphql, ariadne, graphene	pyproject.toml, requirements.txt
gqlgen, graphql-go	go.mod
async-graphql, juniper	Cargo.toml
webonyx/graphql-php, lighthouse	composer.json
GRAPHQL_ENDPOINT env var	.env, .env.example
/graphql route	routing config
ApolloClient, urql, graphql-request	frontend dependencies

---

Schema-First vs Code-First

Detect which approach the project uses before writing any schema or resolver:

Signal	Approach
.graphql / .gql files are the source of truth	Schema-first
Schema generated from code annotations / decorators	Code-first

• Schema-first: SDL (Schema Definition Language) files are committed; resolvers implement the contract.
• Code-first: resolvers are annotated and the schema is generated at build time.

Do not mix approaches. Follow whichever the project already uses.

---

Naming Conventions

Element	Convention	Example
Types	PascalCase	User, OrderItem
Fields	camelCase	createdAt, totalAmount
Queries	camelCase verb-noun	user(id), listOrders
Mutations	camelCase action-noun	createUser, updateOrder, deleteProduct
Subscriptions	camelCase event	orderStatusChanged, messageReceived
Enums	SCREAMING_SNAKE_CASE values	ORDER_STATUS_PENDING
Input types	[Action][Type]Input	CreateUserInput, UpdateOrderInput

Never expose internal database column names directly — map them to clean field names in the schema.

---

Core Rules

These decide the shape of the work. The full patterns and code live in the references below.

Area	Rule
Nullability	Mark a field non-null (!) only when the server truly guarantees a value
Mutation arguments	Wrap in a single input object; return the mutated entity in the payload
Business errors	Return them as data (errors: [UserError!]!), not as top-level GraphQL errors
Related data	Never fetch it in a resolver without a per-request DataLoader — this is the default source of N+1
Collections	Never return an unbounded list; paginate (cursor-based for anything that can grow)
Subscriptions	Filter server-side and enforce the same auth rules as queries
Query hardening	Depth and complexity limits configured; introspection disabled in production

---

References

File	Load when
references/schema-and-operations.md	Writing queries, mutations, pagination, or subscriptions — full SDL patterns
references/resolvers-and-errors.md	Writing or reviewing resolvers — DataLoader batching, error taxonomy, query-level security

---

What to Do Before Declaring Done

• No resolver fetches related data without going through a DataLoader
• All list fields are paginated
• Mutation payloads return the mutated entity
• Business errors use the errors: [UserError!]! pattern
• Subscriptions filter server-side
• Introspection disabled in production config
• Depth/complexity limits configured