Skip to content
Skills Library
Programming · Building & coding

graphql

/graphql

Designs GraphQL schemas, operations, resolvers, federation and query cost controls. Use when editing .graphql SDL or resolvers, a query returns null data or fires hundreds of database calls, writing queries, mutations or fragments, adding a federated subgraph, or deprecating a field without breaking clients.

Repository
hyperskills ↗
Licence
MIT
Last repository change
04.11.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
21
Scripts
4
HTML comments
0
URLs in SKILL.md
0
Deprecation

No signals detected. Repository changed on 04.11.2026, without references to retired models or APIs.

Licence

MIT, open: use and modify while retaining author attribution.

What to check before installing
  • 4 scripts in this package. Review them before installing, as Claude may execute them.

Scripts: evals/files/feed-builder.ts, evals/files/feed-resolvers.js, evals/files/orders-routes.ts, evals/files/yoga-server.ts

What it does and when to use it

Designs GraphQL schemas, operations, resolvers, federation and query cost controls. Use when editing .graphql SDL or resolvers, a query returns null data or fires hundreds of database calls, writing queries, mutations or fragments, adding a federated subgraph, or deprecating a field without breaking clients.

Original author description

Designs GraphQL schemas, operations, resolvers, federation and query cost controls. Use when editing .graphql SDL or resolvers, a query returns null data or fires hundreds of database calls, writing queries, mutations or fragments, adding a federated subgraph, or deprecating a field without breaking clients.

How it works

  1. Scope
  2. Core rules
  3. Workflows
  4. Topic router
  5. Output format
  6. Environment
Original SKILL.md headings · 269 lines, 2,991 words
SKILL.md preview
---
name: graphql
description: "Designs GraphQL schemas, operations, resolvers, federation and query cost controls. Use when editing .graphql SDL or resolvers, a query returns null data or fires hundreds of database calls, writing queries, mutations or fragments, adding a federated subgraph, or deprecating a field without breaking clients."
license: MIT (upstream attributions in NOTICE.md)
metadata:
  author: HyperSkills
  version: "2026.11.04"
  category: framework
---

# graphql

## Scope

Covers the GraphQL API surface itself: schema design (types, field naming, nullability,
interfaces and unions, input objects, enums, custom scalars, global object identification),
pagination, error modelling, writing and reviewing operations, execution performance and
demand control, the differences between server implementations, federated subgraphs,
authorisation placement, introspection, and evolving a schema without breaking clients.

Facts here are checked against the GraphQL specification and graphql.org, then against
**graphql-js 17**, **GraphQL Yoga 6**, **Apollo Server 5** and **Pothos 4** where behaviour
differs by implementation. Rules that hold only for one server say so in the same sentence.

Not covered:

- REST and HTTP contract design — resource modelling, URI and status-code policy, RFC 9457
  error bodies, OpenAPI documents. Use the `api-design` skill. There is no "GraphQL version"
  of those decisions; a question about status codes is a question about HTTP.
- Apollo Client's React bindings and its normalised cache — hooks, `useSuspenseQuery`,
  `cache.modify`, optimistic UI. Use the `react` skill. This skill covers the operation
  documents such a client sends, not how a component subscribes to them.
- The Node process around a GraphQL server — HTTP framework wiring, configuration, logging,
  graceful shutdown, health checks. Use the `nodejs-backend` skill.
- Database schema and query tuning behind the resolvers — indexes, `EXPLAIN`, keyset
  predicates as SQL. Use the `postgres` skill; this skill only says which shape of query a
  batched resolver must ask for.
- Type-level modelling in TypeScript around generated operation types — use the `typescript`
  skill.
- Deciding what deserves a test — use the `test-driven-development` skill; the GraphQL-specific
  question of *what to assert* is in `references/servers.md`.
- Gateway and router operations (deployment topology, YAML configuration, traffic shaping,
  telemetry pipelines) are a product concern of whichever router you run, not part of this
  skill. Read that product's own documentation.

Paths below are relative to this skill's directory.

## Core rules

1. Read the SDL and the server setup before proposing anything. Which implementation is running,
   whether the schema is SDL-first or code-first, and whether this is a single graph or a
   subgraph decide which of these rules have a mechanism behind them in this codebase.
2. Fields are nullable by default deliberately: a networked service can lose a database, a
   downstream call or a field-level authorisation check, and a nullable field lets that one
   position degrade to null instead of failing the request. ` ! ` is a promise the server must
   keep, not a convenience for the client's generated types.
3. An execution error at a non-null response position propagates to its parent position. If the
   parent is nullable it becomes null; if it is also non-null the error keeps climbing. When
   every position from the root to the failure is non-null, the whole `data` entry is null —
   this is how a schema decorated with ` ! ` everywhere produces blank screens.
4. So add ` ! ` only where the position cannot fail independently of its parent: an `id` that came
   with the row, yes; a score from a ranking service, a URL from a CDN, a field one role cannot
   see, no.
5. `[T!]` means one failing element nulls the *entire* list, and a non-null list of those then
   nulls the list's parent. If partial results matter, the element type is what has to be
   nullable.
6. Non-null on the input side is the opposite trade: a required argument or input field costs
   nothing at runtime and removes a whole class of validation. The cost is later — adding a
   required argument or input field (non-null **with no default**) to a shipped schema is a
   breaking change. With a schema default it is not required: old documents still validate and
   the resolver receives the default.
7. Model the domain the clients render, not the tables behind it. A type that mirrors a table
   freezes today's storage layout into a contract you cannot version out of.
8. Return object types rather than scalar foreign keys. A field `author` typed as the `Author`
   object lets a client fetch what it needs; an `authorId` scalar forces a second round trip and
   never grows.
9. Use enums for closed sets instead of free strings, and treat the set as append-only:
   removing or renaming a value is breaking, and adding one breaks input positions and clients
   that switch exhaustively (`references/evolution.md`).
10. Give each mutation a single input object argument named after the operation
    (`placeOrder(input: PlaceOrderInput!)`), and name the mutation after the business operation
    rather than the CRUD verb.
11. A mutation returns a payload type: the affected entity, nullable, plus a non-null list of
    typed errors (userErrors: [UserError!]!). Use a result union instead only when the
    outcomes return genuinely different shapes — a payload can gain fields without breaking
    clients, a union cannot gain members safely.
12. The top-level `errors` array is for exceptional failures — infrastructure, an invalid
    document, missing authentication. Expected domain outcomes (coupon rejected, stock short,
    name taken) belong in the schema where they are discoverable and typed.
13. Never let an unknown error reach a client verbatim. Whether you have to do anything for
    that differs: Yoga masks by default, Apollo Server does not and ships stack traces unless
    `NODE_ENV` is `production` or `test` (`references/errors.md`).
14. Every list field that can grow gets a cursor Connection. This shape comes from the Relay
    cursor connections specification, not from the GraphQL specification, so match it exactly
    or clients' generated helpers will not work (`references/pagination.md`).
15. Give paginated fields a default page size and a server-enforced maximum, and make an
    out-of-range `first`/`last` a request error rather than silently clamping. An uncapped list
    argument is a self-service denial of service.
16. Cursors are opaque to clients and encode the sort key plus a unique tiebreaker, so the
    query behind them is a seek predicate. An offset dressed up as a cursor still duplicates and
    skips rows when the underlying list shifts between requests.
17. Keep exact counts off the hot path: `totalCount` is a separate, expensive query, so leave it
    nullable or off the connection instead of paying for it on every page.
18. Put authorisation in the business-logic layer and have resolvers call into it. Field
    resolvers are one entry point among several; duplicated rules drift, and the graph reaches
    every type it connects, so entry-point-only checks are not checks.
19. Construct DataLoaders per request and hand them to resolvers on the context. A loader
    shared across requests caches rows for the process lifetime, which serves stale data and
    leaks one user's authorised rows into another user's response.
20. A DataLoader batch function must return exactly `keys.length` values in the same order as
    `keys`, using `null` or an `Error` for misses. Returning whatever the database gave back
    silently attaches the wrong parent to the wrong child.
21. Bound the operation, not just the resolvers. Batching removes round trips but a cyclical
    selection set still multiplies work: set a depth limit, a separate smaller limit on nested
    list fields, caps on breadth, aliases and HTTP batching, and a complexity budget rejected at
    validation time — before the first resolver runs (`references/performance.md`).
22. For first-party clients, register the operations at build time and let the client send a
    document id (trusted documents). That is an allowlist, a smaller request, and — over `GET` —
    something a CDN can cache. It does not work for public APIs, where the demand-control limits
    above are the whole defence.
23. Evolve additively: add the new field, deprecate the old one with a reason that names the
    replacement, and remove it only after measured per-field usage reaches zero. Retyping or
    renaming in place is the one change GraphQL gives you no way to survive.
24. Apollo Federation is one implementation of federation, not a specification; the standards
    work is in the GraphQL Foundation's Composite Schemas working group. Write subgraphs against
    the federation version your gateway composes, and check the current directive set rather
    than copying a `@link` version from an example (`references/federation.md`).
25. Finish with the gate for the task you were doing — schema lint, a breaking-change diff, a
    statement count, or composition — and report the command and its output. "It should be
    fine now" is not a result.

## Workflows

### design-or-review-a-schema

- [ ] Start from what clients render, not from the tables: list the screens or use cases, the
      nouns they need, and the largest list each one can return.
- [ ] Name types and fields from the client's vocabulary, and check the mechanical rules
      (PascalCase types, camelCase fields, no `_tbl`/`_id`-scalar smells, enums instead of
      status integers) — `references/schema-design.md`.
- [ ] Audit nullability position by position: for each ` ! `, say what makes that position unable
      to fail independently. Anything crossing a network, a service or a field-level permission
      loses its ` ! `. Do the same for list element types.
- [ ] Give every growable list a Connection with a default and a maximum page size, and decide
      what the cursor encodes (`references/pagination.md`).
- [ ] Model the failures: which outcomes are exceptional (top-level `errors`) and which are
      domain results that belong in a payload's `userErrors` — `references/errors.md`.
- [ ] Decide whether clients need refetch-by-id or cache normalisation; if so, implement global
      object identification with `Node` rather than type-local integer ids.
- [ ] Write descriptions on every type, field and argument, including what a null means for the
      nullable ones.
- [ ] **Gate — the schema survives a hostile client:** `graphql-eslint` passes on the schema, a
      deliberately deep and alias-heavy query is rejected by the configured limits, and killing a
      downstream dependency degrades one field to null instead of nulling `data`.

### write-or-review-an-operation

- [ ] Read the schema first, not the client code: which fields are nullable, which lists are
      connections, which abstract types need `__typename`.
- [ ] Name the operation, pass every dynamic value as a variable, and select only the fields the
      caller uses (`references/operations.md`).
- [ ] Put reusable selections in fragments defined on the type they select from, co-located with
      the component or module that consumes them, rather than repeating field lists.
- [ ] Select `__typename` on every union and interface field, and give the consuming code a
      branch for a type it does not recognise — schemas gain members.
- [ ] Handle the nullable fields as nullable. A non-null assertion on the client side converts a
      graceful partial response into a crash.
- [ ] For paginated fields, take the cursors from `pageInfo`, keep them opaque, and do not mix
      `first`/`after` with `last`/`before` in one request.
- [ ] **Gate — the document is valid and typed:** `graphql-eslint` passes on the operation
      documents, code generation succeeds against the current schema, and the generated types
      show the nullability the code actually handles.

### fix-n-plus-1-or-an-expensive-query

- [ ] Measure before changing: log the statements and outbound calls one representative
      operation issues, so you know the number you are trying to move.
- [ ] Map each resolver that crosses a database or service boundary. Every one that runs once
      per parent row is an N+1, including the ones that look cheap (`count(*)` per row).
- [ ] Add a DataLoader per boundary, constructed per request on the context, with a batch
      function that returns `keys.length` results in key order — `references/performance.md`.
- [ ] For list-valued relationships, batch to one grouped query keyed by the parent id; for
      counts, one grouped aggregate or a counter column, not one statement per parent.
- [ ] Batch outbound service calls the same way rather than per item.
- [ ] Then bound the operation itself: depth, nested-list depth, breadth and alias caps, and a
      complexity budget enforced at validation. Batching a cyclical query only makes it cheaper
      per level, not bounded.
- [ ] Paginate the list fields the expensive selection reached, if they are not paginated already.
- [ ] **Gate — the number moved and stays moved:** re-run the same operation and report statement
      and call counts before and after, and show that the hostile deep query is now rejected
      before execution.

### evolve-a-schema-without-breaking-clients

- [ ] Classify every requested change first: additive (new type, new field, new optional
      argument, new output enum value) or breaking (retype, rename, remove, new argument or input
      field that is non-null with no default, new union member, removed enum value) —
      `references/evolution.md`.
- [ ] For each breaking change, design the additive equivalent: a new field beside the old one,
      a new mutation beside the old one, a new enum value served alongside the old one.
- [ ] Mark the superseded element `@deprecated(reason: "...")` with a reason that names the
      replacement, and keep serving it.
- [ ] Find out who still uses it — per-field usage from your own instrumentation or registry —
      and set removal on measured traffic reaching zero, not on a release count.
- [ ] Tell the clients what to do to be safe next time: default branches on enums, `__typename`
      plus an unknown-type branch on abstract types, no force-unwrapping of nullable fields.
- [ ] Resist versioning the endpoint. A `/graphql/v2` doubles the surface you operate and throws
      away the one property that makes additive evolution work: clients only receive the fields
      they asked for.
- [ ] **Gate — the diff says what you think it says:** run a schema diff against the deployed
      schema (`npx @graphql-inspector/cli diff <old> <new>`, or your registry's check) and show
      that every reported breaking change is one you intended.

### add-or-change-a-federated-subgraph

- [ ] Establish the mechanics of the graph you are joining: which federation version the gateway
      composes, which directives that version provides, and which subgraph currently owns each
      type you are touching.
- [ ] Opt this subgraph in with `extend schema @link(...)`, importing only the directives it
      uses, and take the version from the graph's current one rather than from an example
      (`references/federation.md`).
- [ ] Define entities from the identity the whole graph shares: `@key(fields: "...")` on fields
      that are stable, non-null and resolvable in this subgraph, plus a reference resolver that
      can hydrate an object from that key alone.
- [ ] Decide ownership per field, deliberately: one owning subgraph, `@shareable` where two can
      genuinely resolve the same value, `@override` for a migration in progress, `@inaccessible`
      for something composed but not public.
- [ ] Make sure the reference resolver is batched — it is called once per key the gateway needs,
      which is the federated form of N+1.
- [ ] **Gate — it composes and nothing else breaks:** run composition and the subgraph check
      against the current graph, and confirm no other subgraph's fields changed shape.

## Topic router

| Topic | Read when | File |
|---|---|---|
| Type and field naming, nullability reasoning, interfaces versus unions, input objects and `@oneOf`, enums, custom scalars, global object identification, descriptions | Designing or reviewing any part of the type system | `references/schema-design.md` |
| Relay Connection shape, `pageInfo`, cursor contents and encoding, page-size caps, offset and keyset trade-offs, connections on relationships, `totalCount` | A list field can grow, or paging duplicates and skips rows | `references/pagination.md` |
| Top-level `errors` versus errors-as-data, payload `userErrors`, result unions, error codes and `extensions`, interaction with non-null propagation, masking defaults per server | Choosing how a failure reaches the client, or an error leaks or disappears | `references/errors.md` |
| Operation naming, variables, fragments and co-location, `__typename`, `@skip`/`@include`, `@defer`/`@stream` status, persisted and trusted documents, code generation | Writing or reviewing query, mutation and subscription documents | `references/operations.md` |
| N+1 and DataLoader (per-request lifetime, the batch-function contract), aggregate batching, depth and nested-list limits, breadth and alias caps, complexity analysis, `GET` and CDN caching | An operation is slow or chatty, or the API has no demand control | `references/performance.md` |
| graphql-js, Yoga, Apollo Server and Pothos differences, security-relevant defaults, subscription transports, resolver and context conventions, what to assert in tests | Wiring or hardening a server, or a rule behaves differently than documented | `references/servers.md` |
| Entities and `@key`, reference resolvers, `@external`/`@requires`/`@provides`/`@override`/`@shareable`/`@inaccessible`, composition failures, gateway behaviour | Working in a subgraph or debugging composition | `references/federation.md` |
| Breaking versus additive change classification, `@deprecated`, removal on measured usage, enum and abstract-type evolution, client-side robustness, schema diff gates | Changing anything already served to a client | `references/evolution.md` |

## Output format

When reviewing a schema or an operation, group findings by file and lead each with the location:

```
schema/order.graphql
  L14 Order.trackingNumber: String!  — non-null on a field the carrier populates later.
    A parcel not yet accepted makes Order null, and Query.order is non-null, so data is null.
    -> trackingNumber: String
  L31 Order.lineItems: [LineItem!]!  — unbounded list.
    -> lineItems(first: Int = 20, after: String): LineItemConnection!
```

Then one **Verdict** line naming the single change with the largest effect, and a **Gate** line
with the command that proves it. Order findings by consequence — a nullability chain that can
blank a screen, an unbounded list, a shared loader — not by line number.

## Environment

- Schema and operation linting: `npx @graphql-eslint/eslint-plugin` through an ESLint config, or
  the project's existing lint task. It needs to know where the schema and the documents are; if
  the project has no `graphql-config`, say so rather than guessing paths.
- Breaking-change diff: `npx @graphql-inspector/cli diff <old-schema> <new-schema>`. Both
  arguments accept a file, a URL or a `git:` reference, so the deployed schema can be the
  baseline directly.
- Federated graphs use their gateway's own composition and subgraph checks instead of the plain
  diff; the plain diff cannot see the other subgraphs.
- Verifying `data: null` behaviour needs no tooling: run the operation with the failing
  dependency actually failing and read the response. A unit test that stubs the resolver to
  return a value proves nothing about propagation.
- When a command named here is not the one this project uses, name the project's command instead
  of substituting your own.
Files in this package (21)
  • NOTICE.md 7 KB
  • SKILL.md 20 KB
  • SOURCES.yaml 12 KB
  • evals/evals.json 13 KB
  • evals/files/catalog-schema.graphql 1 KB
  • evals/files/checkout-schema.graphql 1 KB
  • evals/files/feed-builder.ts 1 KB
  • evals/files/feed-resolvers.js 2 KB
  • evals/files/feed-schema.graphql 1 KB
  • evals/files/orders-routes.ts 1 KB
  • evals/files/pr-order-input.graphql 1 KB
  • evals/files/yoga-server.ts 1 KB
  • references/.gitkeep 1 KB
  • references/errors.md 10 KB
  • references/evolution.md 12 KB
  • references/federation.md 11 KB
  • references/operations.md 10 KB
  • references/pagination.md 9 KB
  • references/performance.md 11 KB
  • references/schema-design.md 11 KB
  • references/servers.md 11 KB

Versions

RepositoryScoreLicence
This page · lynricsy/hyperskills100MIT
TerminalSkills/skills100Apache-2.0
nimadorostkar/Claude-Skills-collection100MIT
crowdin/skills100MIT
claude-dev-suite/claude-dev-suite100MIT
muon-m2/magento2-tools100MIT
G1Joshi/Agent-Skills100MIT
chrishuffman5/domain-expert100MIT
arbazkhan971/godmode100MIT

Database snapshot: 13.11.2026 · package version 44c30d22469b (SHA-256 digest of the entire package)

Downloads in the last 30 days: 2 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100graphql-schema-resolvers-apollo
    Use this skill when designing GraphQL schemas, type definitions, resolvers, queries, mutations, and DataLoader caching layers.
  • 100graphql-architect
    Use when designing GraphQL schemas, implementing Apollo Federation, or building real-time subscriptions. Invoke for schema design, resolvers with DataLoader, query optimization, federation directives.
  • 95graphql-expert
    GraphQL API design and implementation. Use when building GraphQL APIs, designing schemas, implementing resolvers, or optimizing GraphQL performance.
  • 100graphql-patterns
    Use when designing or operating GraphQL APIs with schemas, resolvers, authorization, pagination, federation, code generation, and hostile-input controls.
  • 100graphql-expert
    Use when designing GraphQL APIs, reviewing schemas and resolvers, optimizing queries, managing federation, or checking GraphQL security and performance best practices.
  • 90graphql-development
    Build and evolve GraphQL schemas/resolvers with typed contracts, authorization and bounded query work. Use when implementing GraphQL APIs or client operations; use api-design for HTTP transport and preserve the chosen server/client framework.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.