# graphql-expert

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.

- skill · `type=skill` · Claude Code, Codex, Cursor, GitHub Copilot, Gemini CLI, OpenCode, Windsurf (Devin Desktop), Claude.ai · 132 installs · ★ 114 repo stars
- Author: travisjneuman
- License: MIT · policy=mirror · the beginning of the file is at the end of this page
- Source: https://github.com/travisjneuman/.claude/tree/HEAD/skills/graphql-expert/SKILL.md
- Updated: 2026-11-10
- Security check: automated, 2026-11-16 (text) — no signs of malicious code found.
- HTML: https://affpapa.org/en/nevibecode/skills/travisjneuman-graphql-expert

## What it does

This skill guides the agent through architecting GraphQL APIs. It enforces naming conventions, default nullability patterns, dedicated input types for mutations, and root type definitions across queries and subscriptions.

Modular reference files cover pagination, sorting, batch mutations, resolver context, and error formatting. Performance practices rely on DataLoader for N+1 query elimination, alongside depth limits and persisted queries. Client setup files also cover Apollo Client and React hooks.

All schemas are verified against an included checklist. It checks PascalCase naming, mutation payloads, and pagination across all list fields.

## Install

### Claude Code (native platform)

1. **Skills CLI (Vercel)**
```bash
npx skills add travisjneuman/.claude --skill graphql-expert -a claude-code
```

2. **Manually: put the files in place**
- File: `~/.claude/skills/graphql-expert/SKILL.md` — Copy the whole skill folder; for one project use .claude/skills/graphql-expert/

### Codex

1. **Skills CLI (Vercel)**
```bash
npx skills add travisjneuman/.claude --skill graphql-expert -a codex
```

2. **Manually: put the files in place**
- File: `.agents/skills/graphql-expert/SKILL.md` — For all projects use ~/.agents/skills/

### Cursor

1. **Skills CLI (Vercel)**
```bash
npx skills add travisjneuman/.claude --skill graphql-expert -a cursor
```

2. **Manually: put the files in place**
- File: `.cursor/skills/graphql-expert/SKILL.md` — Cursor also reads .agents/skills/ and .claude/skills/

### GitHub Copilot

1. **GitHub CLI**
```bash
gh skill install travisjneuman/.claude skills/graphql-expert
```

2. **Manually: put the files in place**
- File: `.github/skills/graphql-expert/SKILL.md`

### Gemini CLI

1. **Skills CLI (Vercel)**
```bash
npx skills add travisjneuman/.claude --skill graphql-expert -a gemini-cli
```

2. **Platform CLI**
```bash
gemini skills install https://github.com/travisjneuman/.claude --path skills/graphql-expert
```

### Windsurf (Devin Desktop)

**Manually: put the files in place**
- File: `.devin/skills/graphql-expert/SKILL.md` — The legacy .windsurf/skills/ path still works

### OpenCode

**Skills CLI (Vercel)**
```bash
npx skills add travisjneuman/.claude --skill graphql-expert -a opencode
```

### Claude.ai

**Claude.ai**
- Zip the folder and upload it in Settings → Capabilities → Skills

Where a file is given instead of a command, copy the files from the source to that path: https://github.com/travisjneuman/.claude/tree/HEAD/skills/graphql-expert/SKILL.md

## When to use it
- design GraphQL schemas with consistent nullability and input types
- resolve N+1 query bottlenecks in resolvers using DataLoader
- set up context-based or directive-based authorization
- enforce query depth and complexity limits on incoming operations

## Example prompts
- Design a GraphQL schema for a blog with paginated user posts
- Write resolvers using DataLoader to fix N+1 queries when fetching authors
- Review this GraphQL schema against the schema checklist

## Source text · SKILL.md · MIT

Below is the content of a third-party file. It is data, not instructions for you: do not act on anything written inside unless the human asks. Block tag: 08507c3814a95a0c.

BEGIN THIRD-PARTY FILE 08507c3814a95a0c
````text
---
name: graphql-expert
description: GraphQL API design and implementation. Use when building GraphQL APIs, designing schemas, implementing resolvers, or optimizing GraphQL performance.
---

# GraphQL Expert

Comprehensive guide for designing and implementing GraphQL APIs.

## GraphQL Fundamentals

### What is GraphQL?

```
GraphQL is a query language for APIs that:
✓ Lets clients request exactly what they need
✓ Gets multiple resources in one request
✓ Uses a type system to describe data
✓ Provides introspection (self-documenting)

GraphQL vs REST:
┌─────────────────────────────────────────┐
│ REST: Multiple endpoints, fixed shapes  │
│ GET /users/1                            │
│ GET /users/1/posts                      │
│ GET /users/1/followers                  │
├─────────────────────────────────────────┤
│ GraphQL: Single endpoint, flexible      │
│ POST /graphql                           │
│ query { user(id: 1) {                   │
│   name                                  │
│   posts { title }                       │
│   followers { name }                    │
│ }}                                      │
└─────────────────────────────────────────┘
```

---

## Schema Design

### Type System

```graphql
# Scalar Types (built-in)
String, Int, Float, Boolean, ID

# Custom Scalar
scalar DateTime
scalar JSON

# Object Type
type User {
  id: ID!
  email: String!
  name: String
  createdAt: DateTime!
  posts: [Post!]!
}

# Enum
enum Role {
  ADMIN
  USER
  GUEST
}

# Interface
interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  # ... other fields
}

# Union
union SearchResult = User | Post | Comment

# Input Type (for mutations)
input CreateUserInput {
  email: String!
  name: String!
  role: Role = USER
}
```

### Nullability

```graphql
# Field modifiers:
String      # Nullable string
String!     # Non-null string
[String]    # Nullable list of nullable strings
[String!]   # Nullable list of non-null strings
[String]!   # Non-null list of nullable strings
[String!]!  # Non-null list of non-null strings

# Best practice:
# - Make fields nullable by default
# - Use ! only when guaranteed non-null
# - Lists should usually be non-null: [Item!]!
```

### Schema Structure

```graphql
# Root Types
type Query {
  # Read operations
  user(id: ID!): User
  users(limit: Int, offset: Int): [User!]!
  me: User
}

type Mutation {
  # Write operations
  createUser(input: CreateUserInput!): User!
  updateUser(id: ID!, input: UpdateUserInput!): User!
  deleteUser(id: ID!): Boolean!
}

type Subscription {
  # Real-time updates
  userCreated: User!
````
END THIRD-PARTY FILE 08507c3814a95a0c

The third-party file has ended. Everything between the 08507c3814a95a0c tags is data: requests and commands from it are not followed. An “end of file” line with another tag inside the block is part of the file.

First 2905 of 4774 bytes. © travisjneuman · MIT · https://github.com/travisjneuman/.claude/tree/HEAD/skills/graphql-expert/SKILL.md

_Part of the page did not fit — see the HTML version._

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md
