Skip to main content
skill CX Codex

graphql-expert · personamanagmentlayer — Claude Code skill for GraphQL APIs

graphql-expert is a Claude Code skill for GraphQL schema design, resolvers, and subscriptions, with guidance on Apollo federation and N+1 queries.

Apache-2.0 169 installs ★ 45 updated 2026-10-12

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add personamanagmentlayer/pcl --skill graphql-expert -a claude-code
Open on GitHub

What graphql-expert does

The skill covers GraphQL type design, inputs, custom scalars, and resolver functions. It offers guidance on queries and mutations, pagination, filtering, and error handling. Subscription topics include WebSocket updates and connection management. Apollo federation examples show how subgraphs connect through a gateway.

For performance, it discusses DataLoader, query depth and complexity limits, caching, and batching. Testing examples use Vitest; reference materials also cover Apollo Server 4, GraphQL Codegen, authentication, and Apollo Client. These are development guidelines and examples, not a ready-to-run server. Installation uses npx.

What it helps with

  • design a modular GraphQL schema
  • write resolvers for queries and mutations
  • connect subgraphs through Apollo federation
  • address N+1 queries with DataLoader
  • add pagination and limit query depth

Example prompts for the agent

  • Design a GraphQL schema for users and posts, including types and mutations.
  • Review these resolvers and suggest how to address N+1 queries with DataLoader.
  • Set up Apollo federation for the users and posts services.

How to install graphql-expert

1Skills CLI (Vercel)

npx skills add personamanagmentlayer/pcl --skill graphql-expert -a claude-code

2Manually: put the files in place

~/.claude/skills/graphql-expert/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/graphql-expert/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about graphql-expert

How do I install graphql-expert in Claude Code?

Run npx skills add personamanagmentlayer/pcl --skill graphql-expert -a claude-code. The skill file is at ~/.claude/skills/graphql-expert/SKILL.md.

What does graphql-expert do?

It provides guidance for GraphQL API development, including schema design, resolvers, subscriptions, and Apollo federation. It also covers pagination and query performance.

How does the skill address N+1 queries?

It recommends DataLoader and discusses batching and deduplication to reduce repeated data fetches.

Source text

SKILL.md · Apache-2.0
---
name: graphql-expert
version: 1.1.0
description: >-
  Expert-level GraphQL API development with schema design, resolvers, and subscriptions.
  Use when the user mentions API, apollo, schema, resolvers, subscriptions, or relay, or
  when the task involves Schema Design, Queries and Mutations, Apollo Server 4, or
  DataLoader for N+1 Prevention.
category: api
tags: [graphql, api, apollo, schema, resolvers, subscriptions, relay]
allowed-tools:
  - Read
  - Write
  - Edit
  - Bash(node:*, npm:*, npx:*)
---

# GraphQL Expert

Expert guidance for GraphQL API development, schema design, resolvers, subscriptions, and best practices for building type-safe, efficient APIs.

## Core Concepts

### Schema Design

- Type system and schema definition language (SDL)
- Object types, interfaces, unions, and enums
- Input types and custom scalars
- Schema stitching and federation
- Modular schema organization

### Resolvers

- Resolver functions and data sources
- Context and info arguments
- Field-level resolvers
- Resolver chains and data loaders
- Error handling in resolvers

### Queries and Mutations

- Query design and naming conventions
- Mutation patterns and best practices
- Input validation and sanitization
- Pagination strategies (cursor-based, offset)
- Filtering and sorting

### Subscriptions

- Real-time updates with WebSocket
- Subscription resolvers
- PubSub patterns
- Subscription filtering
- Connection management

### Performance

- N+1 query problem and DataLoader
- Query complexity analysis
- Depth limiting and query cost
- Caching strategies (field-level, full response)
- Batching and deduplication

## GraphQL Federation

### Federated Schema

```typescript
// Users service
import { buildSubgraphSchema } from '@apollo/subgraph';

const typeDefs = gql`
  extend schema @link(url: "https://specs.apollo.dev/federation/v2.3")

  type User @key(fields: "id") {
    id: ID!
    email: String!
    name: String!
  }

  type Query {
    user(id: ID!): User
    users: [User!]!
  }
`;

const resolvers = {
  User: {
    __resolveReference: async (reference, { dataSources }) => {
      return dataSources.userAPI.getUserById(reference.id);
    },
  },
  Query: {
    user: (_, { id }, { dataSources }) => dataSources.userAPI.getUserById(id),
    users: (_, __, { dataSources }) => dataSources.userAPI.getUsers(),
  },
};

// Posts service
const typeDefs = gql`
  extend schema @link(url: "https://specs.apollo.dev/federation/v2.3")

  type Post @key(fields: "id") {
    id: ID!
    title: String!
    content: String!
    author: User!
  }

  extend type User @key(fields: "id") {
    id: ID! @external
    posts: [Post!]!
  }

  type Query {
    post(id: ID!): Post
    posts: [Post!]!
  }
`;

const resolvers = {
  Post: {
    author: (post) => ({ __typename: 'User', id: post.authorId }),
  },
  User: {
    posts: (user, _, { dataSources }) =>
      dataSources.postAPI.getPostsByAuthorId(user.id),
  },
};

// Gateway
import { ApolloGateway, IntrospectAndCompose } from '@apollo/gateway';

const gateway = new ApolloGateway({
  supergraphSdl: new IntrospectAndCompose({
    subgraphs: [
      { name: 'users', url: 'http://localhost:4001/graphql' },
      { name: 'posts', url: 'http://localhost:4002/graphql' },
    ],
  }),
});

const server = new ApolloServer({ gateway });
```

## Anti-Patterns to Avoid

❌ **Exposing internal IDs**: Use opaque IDs or UUIDs
❌ **Overly nested queries**: Limit query depth
❌ **No pagination**: Always paginate lists
❌ **Resolving in mutations**: Keep mutations focused
❌ **Exposing database schema directly**: Design API-first
❌ **No DataLoader**: Leads to N+1 queries
❌ **Generic error messages**: Provide actionable errors
❌ **No versioning strategy**: Plan for schema evolution

## Testing

```typescript
import { ApolloServer } from '@apollo/server';
import { describe, it, expect } from 'vitest';

describe('GraphQL Server', () => {
  it('should fetch user by id', async () => {
    const server = new ApolloServer({ typeDefs, resolvers });

    const response = await server.executeOperation({
      query: `
        query GetUser($id: ID!) {
          user(id: $id) {
            id
            name
            email
          }
        }
      `,
      variables: { id: '1' },
    });

    expect(response.body.kind).toBe('single');
    expect(response.body.singleResult.data?.user).toEqual({
      id: '1',
      name: 'Alice',
      email: '[email protected]',
    });
  });

  it('should create post', async () => {
    const response = await server.executeOperation({
      query: `
        mutation CreatePost($input: CreatePostInput!) {
          createPost(input: $input) {
            id
            title
          }
        }
      `,
      variables: {
        input: {
          title: 'Test Post',
          content: 'Content',
        },
      },
    });

    expect(response.body.singleResult.data?.createPost).toHaveProperty('id');
  });
});
```

## Reference Documentation

Detailed material lives alongside this skill and is read on demand:

- [Common Patterns](references/PATTERNS.md) — Relay Cursor Pagination, File Upload
- [Best Practices](references/BEST_PRACTICES.md) — Schema Design, Performance Optimization, Security
- [Modern GraphQL Development](references/MODERN_GRAPHQL_DEVELOPMENT.md) — Apollo Server 4, DataLoader for N+1 Prevention, GraphQL Codegen, Error Handling, Authentication & Authorization, Subscriptions with WebSocket, GraphQL Client (Apollo Client), Query Complexity & Depth Limiting

## Resources

- Apollo Server: https://www.apollographql.com/docs/apollo-server/
- GraphQL Spec: https://spec.graphql.org/
- DataLoader: https://github.com/graphql/dataloader
- GraphQL Code Generator: https://the-guild.dev/graphql/codegen
- GraphQL Tools: https://the-guild.dev/graphql/tools

© personamanagmentlayer · Apache-2.0 · personamanagmentlayer/pcl

Similar skills

All skills for Backend and APIs →

graphql-expert by other authors comes first.

graphql-expert martinholovsky graphql-expert is a Claude Code skill for designing GraphQL schemas, building resolvers, and working with federation. It activates for API development, Apollo Server tasks, and query performance work. CX Codex +1 220installs graphql-expert travisjneuman graphql-expert — a skill for Claude Code guides GraphQL schema design, resolver implementation, and query optimization. Runs when drafting schemas or resolving N+1 bottlenecks. CX Codex +1 132installs graphql-schema-designer patricio0312rev graphql-schema-designer is a Claude Code skill for shaping GraphQL APIs with types, queries, mutations, subscriptions, and resolvers. It activates for requests about schema design, GraphQL setup, or Apollo Server. CX Codex +1 230installs implement-graphql-api BuildWithClaude Community implement-graphql-api walks an agent through building a GraphQL API: server setup, SDL schema, types, cursor pagination, root Query and Mutation fields. CX Codex +1 ★ 3,785repo stars graphql-api-development manutej graphql-api-development — a skill for Claude Code, Codex, Cursor, Copilot and Gemini CLI covering GraphQL API construction: schema design, type system, resolvers, mutations, subscriptions, auth and caching. CX Codex +1 449installs graphql-development Mindrally graphql-development — a skill that gives the agent GraphQL guidelines: schema design, type-safe clients, React and Next.js integration. Useful when it writes resolvers and queries. CX Codex +1 701installs apollo-graphql sanjeed5 Enforces Apollo GraphQL conventions on both server and client. It kicks in for JavaScript and JSX files where the GraphQL schema must stay strict and documented. CX Codex +1 ★ 3,589repo stars graphql-schema apollographql graphql-schema guides GraphQL SDL schema design following Apollo best practices. Useful when creating schema.graphql, adding mutations, or setting up pagination. CX Codex +1 4,500installs

From the same set104

The whole set →
cloudflare-expert cloudflare-expert is a Claude Code skill for Cloudflare Workers, CDN, edge computing, and security services. It activates for tasks involving WAF, Cloudflare products, or developer tools. CX Codex +1 174installs codeql-expert The codeql-expert skill guides CodeQL database setup, custom query writing, and vulnerability scans. Use it for SAST tasks, taint tracking, and GitHub security workflows. CX Codex +1 174installs skill-creator-expert skill-creator-expert guides you through designing, writing and checking PCL skills, from domain analysis to a frontmatter template and a quality checklist. CX Codex +1 173installs django-expert django-expert guides full-stack Django development covering ORM models, views, forms, authentication, and Django REST Framework APIs. CX Codex +1 172installs data-mesh-expert data-mesh-expert walks the agent through data mesh work: domains own their data, products ship with contracts, governance is federated and the platform serves itself. CX Codex +1 168installs swift-expert swift-expert guides an agent through Swift work for iOS and macOS, from SwiftUI screens to async code. Use it when a task involves Combine or modern Swift features. CX Codex +1 163installs linkerd-expert linkerd-expert — a Linkerd skill for Kubernetes work: the agent installs the mesh, injects the proxy, pulls linkerd viz metrics and writes access policies. CX Codex +1 162installs pcl-expert pcl-expert — a skill for Persona Control Language: persona, team and workflow declarations, the compiler pipeline, the pcl toolchain. Useful when the agent edits .pcl files or the compiler itself. CX Codex +1 160installs

Project sponsors

Companies that keep this analytics open