Skip to content
Skills Library
Programming · Building & coding

graphql

/graphql

Use when designing or operating a GraphQL API. Covers schema design, resolver performance and DataLoader batching, query cost limiting, error handling, and federation. Trigger on "graphql query is slow", "n+1 in my resolvers", "set up dataloader", "limit query depth on our graphql endpoint". Do not use for REST endpoint design — see the api-design skill.

Licence
MIT
Last repository change
24.10.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
1
Scripts
0
HTML comments
0
URLs in SKILL.md
0
Deprecation

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

Licence

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

What it does and when to use it

Use when designing or operating a GraphQL API. Covers schema design, resolver performance and DataLoader batching, query cost limiting, error handling, and federation. Trigger on "graphql query is slow", "n+1 in my resolvers", "set up dataloader", "limit query depth on our graphql endpoint". Do not use for REST endpoint design — see the api-design skill.

Triggers from the description

graphql query is slown+1 in my resolversset up dataloaderlimit query depth on our graphql endpoint
Original author description

Use when designing or operating a GraphQL API. Covers schema design, resolver performance and DataLoader batching, query cost limiting, error handling, and federation. Trigger on "graphql query is slow", "n+1 in my resolvers", "set up dataloader", "limit query depth on our graphql endpoint". Do not use for REST endpoint design — see the api-design skill.

How it works

  1. Purpose
  2. When to Use
  3. Capabilities
  4. Inputs
  5. Outputs
  6. Workflow
  7. Best Practices
  8. Examples
  9. Notes
Original SKILL.md headings · 93 lines, 621 words
SKILL.md preview
---
name: graphql
description: Use when designing or operating a GraphQL API. Covers schema design, resolver performance and DataLoader batching, query cost limiting, error handling, and federation. Trigger on "graphql query is slow", "n+1 in my resolvers", "set up dataloader", "limit query depth on our graphql endpoint". Do not use for REST endpoint design — see the api-design skill.
metadata:
  category: backend
  version: 1.0.0
  tags: [graphql, schema, dataloader, federation, performance]
---

# GraphQL

## Purpose

Design a GraphQL schema that models the domain rather than the database, and operate it without letting a single query take down the service.

## When to Use

- Designing a GraphQL schema from scratch.
- Diagnosing slow queries or N+1 resolver behavior.
- Protecting a public GraphQL endpoint from expensive queries.
- Splitting a schema across services with federation.

## Capabilities

- Schema design: types, interfaces, unions, connections, nullability.
- Resolver architecture and DataLoader batching.
- Query cost analysis, depth limiting, and persisted queries.
- Error handling that distinguishes partial failures from total ones.
- Federation and schema composition.

## Inputs

- The domain model and the client's actual query patterns.
- The data sources behind each field.
- Whether the endpoint is public (untrusted queries) or internal.

## Outputs

- A schema with deliberate nullability and stable field names.
- Resolvers that batch, with no N+1 on any documented query.
- Cost limits and a persisted-query allow-list for public endpoints.

## Workflow

1. **Design for the client, not the tables** — The schema is a product surface. If it mirrors your database, you have built a slower REST API with worse caching.
2. **Get nullability right early** — A nullable field is a permanent client burden; a non-null field that later fails takes down the whole parent object. Non-null for genuine invariants only.
3. **Batch every relation** — Every resolver that fetches by id gets a DataLoader. Without one, `orders { customer { name } }` issues one query per order.
4. **Bound the cost** — Depth limit, complexity limit, and pagination caps. Then persisted queries for first-party clients.
5. **Model errors explicitly** — Expected failures (validation, not found) belong in the schema as union results; unexpected failures go to `errors`.

## Best Practices

- Never expose an unbounded list field. Use the Connection pattern with a `first`/`after` cap.
- `DataLoader` instances are per-request. A shared loader is a cache-poisoning bug across users.
- Changing a field from nullable to non-null is a breaking change for clients that handle null; the reverse is breaking for clients that do not. Get it right before launch.
- Do not version a GraphQL schema. Add fields, deprecate old ones with `@deprecated(reason:)`, and remove them once usage reaches zero.
- Instrument per-field resolver latency. The slow field is never the one you would guess.
- Introspection on a public production endpoint is a reconnaissance gift. Disable it or restrict it.

## Examples

**DataLoader eliminating an N+1:**

```typescript
// Without a loader: 1 query for orders, then N queries for customers.
const resolvers = {
  Order: {
    customer: (order, _args, ctx) => ctx.loaders.customer.load(order.customerId),
  },
};

// The loader batches every customerId requested in the same tick into one query.
export function createLoaders(db: Db) {
  return {
    customer: new DataLoader<string, Customer>(async (ids) => {
      const rows = await db.customers.findMany({ where: { id: { in: [...ids] } } });
      const byId = new Map(rows.map((r) => [r.id, r]));
      return ids.map((id) => byId.get(id) ?? new Error(`Customer ${id} not found`));
    }),
  };
}
```

**Expected failures modeled in the schema:**

```graphql
union CreateOrderResult = Order | ValidationFailed | InsufficientInventory

type Mutation {
  createOrder(input: CreateOrderInput!): CreateOrderResult!
}
```

The client must handle each outcome. Business failures no longer masquerade as transport errors.

## Notes

- Query complexity limits must be tuned against real queries, not guessed. Log the complexity of every production query for a week before enforcing a ceiling.
- Federation solves an organizational problem (independent teams owning parts of the graph), not a technical one. If one team owns the whole schema, a single service is simpler.
- GraphQL over HTTP GET with persisted queries restores CDN caching, which naive POST-based GraphQL throws away.

Versions

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

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

Downloads in the last 30 days: 0 · ranking

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

Similar skills

  • 95graphql-resolvers
    Use when implementing GraphQL resolvers with resolver functions, context management, DataLoader batching, error handling, authentication, and testing strategies.
  • 100graphql-n-plus-one-dataloader
    Diagnose and eliminate the GraphQL N+1 resolver explosion using Facebook DataLoader's per-request batching, plus the second-order defenses (persisted queries, depth limits, cost analysis). Use when a GraphQL query that returns N items in a list triggers N+1 database round trips,…
  • 95backend-graphql-optimization
    Use this skill when the user says 'graphql n+1', 'dataloader', 'graphql slow', 'graphql performance', 'batch resolvers', 'query complexity', 'depth limit', 'persisted queries', 'graphql caching'. Diagnoses and fixes GraphQL server performance: N+1 resolver queries with…
  • 100graphql-api-design
    Design GraphQL APIs with well-structured schemas, efficient resolvers, pagination, and performance patterns like DataLoader and federation. Use when the user requests graphql api design or provides relevant inputs for this workflow.
  • 100graphql-apis
    Builds and reviews GraphQL APIs - schema design (nullability, connections, input and payload types, errors as data), per-request DataLoader batching for N+1, depth and cost limits, persisted queries, field-level authorization, schema evolution with deprecation and usage data,…
  • 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.

Feedback and reports

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