🎯

graphql

🎯Skill
g1joshi/agent-skills2 Installs9Last Updated Feb 10, 2026

Installation

$npx skills add g1joshi/agent-skills --skill graphql

Run it in a terminal; it asks which AI coding tools to install it for (Claude Code, Codex, Cursor and more).

Uses skills.sh Β· Node.js 22.20+

After installing

Ask for related work and the agent uses it on its own, or call it yourself.

Run it (Claude Code)/graphql
Install by hand

Copy the whole skill folder from GitHub to the place below. Copying only SKILL.md can leave out files the skill uses.

Open the skill folder β†’
  • This project .claude/skills/graphql/
  • All projects ~/.claude/skills/graphql/

These paths are for Claude Code. For other tools, the command above puts it in the right place.

Expert GraphQL architecture assistance covering schema definition language (SDL), resolver design, DataLoader batching, schema stitching/federation, and client caching. Use when designing GraphQL APIs, preventing N+1 query problems, building Apollo/Relay schemas, or aggregating data from multiple services.

GraphQL

GraphQL is a query language for APIs and a runtime for fulfilling those queries with your existing data. It gives clients the power to ask for exactly what they need and nothing more.

When to Use

  • Client-Driven Data Fetching: Web and mobile clients with drastically different UI layout requirements consuming the same API.
  • Over-Fetching & Under-Fetching Mitigation: Allowing clients to request the exact fields needed for a view in a single HTTP request.
  • API Aggregation & Federated Supergraphs: Combining dozens of microservice APIs into a unified GraphQL schema via Apollo Federation.
  • Real-Time Subscriptions: Streaming live changes to clients over WebSockets or HTTP Server-Sent Events (SSE).

Quick Start

# The Schema
type User {
  id: ID!
  name: String!
  orders: [Order]
}

type Query {
  user(id: ID!): User
}
// The Query (Client)
query {
  user(id: "123") {
    name
    orders {
      total
      status
    }
  }
}

Core Concepts

Strongly-Typed Schema Definition (SDL)

Defines types, relationships, queries, and mutations strictly:

# schema.graphql
type Query {
  project(id: ID!): Project
}

type Mutation {
  assignTask(input: AssignTaskInput!): Task!
}

type Project {
  id: ID!
  name: String!
  tasks(status: TaskStatus): [Task!]!
}

type Task {
  id: ID!
  title: String!
  assignee: User
}

Resolvers & Hierarchical Execution

Each field on a type maps to an independent resolver function:

// resolvers.ts
export const resolvers = {
  Query: {
    project: async (_parent, { id }, ctx) => ctx.db.getProject(id),
  },
  Project: {
    // Resolved only if the client requested the "tasks" field
    tasks: async (project, { status }, ctx) =>
      ctx.db.getTasksForProject(project.id, status),
  },
};

DataLoader Request Batching & Deduplication

Batches individual resolver database lookups into a single SQL IN query to prevent N+1 query storms:

import DataLoader from "dataloader";

export function createUserDataLoader(db: Database) {
  return new DataLoader(async (userIds: readonly string[]) => {
    const users = await db.query("SELECT * FROM users WHERE id = ANY($1)", [
      userIds,
    ]);
    const userMap = new Map(users.map((u) => [u.id, u]));
    return userIds.map((id) => userMap.get(id) || null);
  });
}

Common Patterns

DataLoader N+1 Query Prevention

Problem: Nested resolvers trigger separate SQL queries for each child record (N+1 database reads).
Solution: Batch and cache database reads using DataLoader.

import DataLoader from "dataloader";

// Batch function receives array of IDs collected across concurrent resolvers
const authorLoader = new DataLoader(async (authorIds: readonly string[]) => {
  const authors = await db
    .select()
    .from(authorsTable)
    .where(inArray(authorsTable.id, authorIds as string[]));
  const authorMap = new Map(authors.map((a) => [a.id, a]));
  return authorIds.map((id) => authorMap.get(id) || null);
});

// Resolver consumes DataLoader
export const resolvers = {
  Book: {
    author: (book: { authorId: string }) => authorLoader.load(book.authorId),
  },
};

Best Practices

Do:

  • Always Use DataLoader for Relational Fields: Never allow nested child resolvers to execute raw database queries in a loop.
  • Implement Query Complexity Limits: Use libraries like graphql-query-complexity to reject nested query abuse before execution.
  • Paginate List Fields with Cursors: Follow the Relay Connection specification (edges, node, pageInfo) for robust infinite scroll.
  • Persist Queries in Production: Use Persisted Queries (hashes) to prevent arbitrary unbounded query submission from untrusted clients.

Don't:

  • Expose internal database schemas directly as GraphQL types: Design domain schemas optimized for frontend views.
  • Return generic HTTP 500 errors for business failures: Return structured validation errors inside GraphQL response payloads.
  • Ignore HTTP caching: GraphQL POST requests bypass browser caches; use CDN Edge caching with Cache-Control headers.

Troubleshooting

ErrorCauseSolution
Cannot query fieldTypo or field restricted.Check Schema and Introspection.
N+1 PerformanceSlow response on lists.Implement DataLoader.
CachingHard to cache via HTTP.Use Normalized Caching in Client (Apollo Client/Urql).

References

More from this repository10