graphql

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

SKILL.md

GitHub

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