Index of every page on this site: llms.txt
All skills
apollographql avatar

/graphql-operations

@9dda139 official
by Apollo GraphQLapollographql/skills134 stars
14
Run it yourself

Guide for writing GraphQL operations (queries, mutations, fragments) following best practices. Use this skill when: (1) writing GraphQL queries or mutations, (2) organizing operations with fragments, (3) optimizing data fetching patterns, (4) setting up type generation or linting, (5) reviewing operations for efficiency.

Use this Skill: https://skilld.dev/gh/apollographql/skills/graphql-operations

Nothing lands on disk. Nothing to clean up.

Fork this Skill

Edit a local copy. It keeps the author and licence.

SKILL.md

≈86 tokens for metadata: the name and description. ≈1.2k when used: this file. ≈9.6k more on demand in 5 files.

Description uses 4.3% of example budget

Before choosing a Skill, your Agent reads its name and description. All available Skills share that space.

  • A shorter description leaves more room for other Skills. This entry exceeds our 1% size suggestion.

In our Claude Code example, all Skill names and descriptions share 8,000 characters. This Skill uses ≈343 characters, or 4.3%.

The 1% threshold is a size suggestion. Longer descriptions can still fit.

Your model, settings, and other Skills decide how much text your Agent can read.

Example settings and source

The example uses a 200k-token context and default Claude Code settings. The count includes the name, description, separators, and when_to_use when present. Codex also counts local file paths.

Skit's source and limits: Codex 0.160.1, Claude Code 2.1.292.

GraphQL Operations Guide

This guide covers best practices for writing GraphQL operations (queries, mutations, subscriptions) as a client developer. Well-written operations are efficient, type-safe, and maintainable.

Start From the Schema

Write every operation against the project's schema, not against the examples in this guide.

  1. Find the schema before you write anything. Check the schema entry in codegen.ts, graphql.config.*, or apollo.config.*, then look for *.graphql SDL files.
  2. Use only the fields, arguments, and enum values that the schema defines. Field names in this guide, such as updatedAt or orderBy: { field: CREATED_AT, direction: DESC }, are illustrations.
  3. Save the operation as a document next to the client's existing operations. Leave the server schema unchanged unless the user asks for a schema change.

Operation Basics

Query Structure

query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
  }
}

Mutation Structure

mutation CreatePost($input: CreatePostInput!) {
  createPost(input: $input) {
    id
    title
    createdAt
  }
}

Subscription Structure

subscription OnMessageReceived($channelId: ID!) {
  messageReceived(channelId: $channelId) {
    id
    content
    sender {
      id
      name
    }
  }
}

Quick Reference

Operation Naming

Pattern Example
Query GetUser, ListPosts, SearchProducts
Mutation CreateUser, UpdatePost, DeleteComment
Subscription OnMessageReceived, OnUserStatusChanged

Variable Syntax

# Required variable
query GetUser($id: ID!) { ... }

# Optional variable with default
query ListPosts($first: Int = 20) { ... }

# Multiple variables
query SearchPosts($query: String!, $status: PostStatus, $first: Int = 10) { ... }

Fragment Syntax

# Define fragment
fragment UserBasicInfo on User {
  id
  name
  avatarUrl
}

# Use fragment
query GetUser($id: ID!) {
  user(id: $id) {
    ...UserBasicInfo
    email
  }
}

Directives

query GetUser($id: ID!, $includeEmail: Boolean!) {
  user(id: $id) {
    id
    name
    email @include(if: $includeEmail)
  }
}

query GetPosts($skipDrafts: Boolean!) {
  posts {
    id
    title
    draft @skip(if: $skipDrafts)
  }
}

Key Principles

1. Request Only What You Need

# Good: Specific fields
query GetUserName($id: ID!) {
  user(id: $id) {
    id
    name
  }
}

# Avoid: Over-fetching
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
    email
    bio
    posts {
      id
      title
      content
      comments {
        id
      }
    }
    followers {
      id
      name
    }
    # ... many unused fields
  }
}

2. Name All Operations

# Good: Named operation
query GetUserPosts($userId: ID!) {
  user(id: $userId) {
    posts {
      id
      title
    }
  }
}

# Avoid: Anonymous operation
query {
  user(id: "123") {
    posts {
      id
      title
    }
  }
}

3. Use Variables, Not Inline Values

# Good: Variables
query GetUser($id: ID!) {
  user(id: $id) {
    id
    name
  }
}

# Avoid: Hardcoded values
query {
  user(id: "123") {
    id
    name
  }
}

4. Colocate Fragments with Components

// UserAvatar.tsx
export const USER_AVATAR_FRAGMENT = gql`
  fragment UserAvatar on User {
    id
    name
    avatarUrl
  }
`;

function UserAvatar({ user }) {
  return <img src={user.avatarUrl} alt={user.name} />;
}

Reference Files

Detailed documentation for specific topics:

  • Queries - Query patterns and optimization
  • Mutations - Mutation patterns and error handling
  • Fragments - Fragment organization and reuse
  • Variables - Variable usage and types
  • Tooling - Code generation and linting

Ground Rules

  • ALWAYS read the project's schema first, and use only the fields, arguments, and enum values it defines
  • ALWAYS name your operations (no anonymous queries/mutations)
  • ALWAYS use variables for dynamic values
  • ALWAYS request only the fields you need
  • ALWAYS include id field for cacheable types
  • NEVER hardcode values in operations
  • NEVER duplicate field selections across files
  • PREFER fragments for reusable field selections
  • PREFER colocating fragments with components
  • USE descriptive operation names that reflect purpose
  • USE @include/@skip for conditional fields

Source: SKILL.md on GitHub

skilld matched fixed text patterns in SKILL.md and file names. Patterns miss obfuscated code.

skilld run checks every file with the same patterns. It asks for approval before it loads a Skill with a behavior marked Needs approval.

1 warning1mo5 checks · Risk SAFE
  • Gen Agent Trust Hub1mo

    The skill is a comprehensive guide for writing GraphQL operations and setting up associated development tools. It contains only instructional content and standard developer workflow examples. No security risks were identified.

  • Socket1mo

    No alerts

  • Snyk1mo

    Risk: LOW · No issues

  • Runlayer9mo

    6/6 files flagged

  • ZeroLeaks7mo

    Score: 93/100 · 2 sections analyzed

Signed by skilld at 9dda139. This ties the file your Agent reads to that commit on GitHub. It does not review the instructions.

Last checked against GitHub 3 weeks ago.

Activeupdated 2 months ago
What it can do
Runs commands
compatibility
Any GraphQL client (Apollo Client, urql, Relay, etc.)
metadata
{
  "author": "apollographql",
  "version": "1.0.1"
}
All 1 allowed tools
Bash(npm:*) Bash(npx:*) Read Write Edit Glob Grep
  • graphql
  • queries
  • mutations
  • fragments
  • apollo-client
  • type-generation
  • best-practices
  • variables

README badge

README badge for apollographql/skills/graphql-operations

Teaches best practices for writing GraphQL operations (queries, mutations, subscriptions) and organizing them with fragments. Covers naming conventions, variable usage, field selection optimization, and colocating fragments with components across Apollo Client and other GraphQL clients.

Generated from the current SKILL.md.

Does this skill work with Apollo Client, urql, and other GraphQL clients?
Yes. The skill covers GraphQL operation best practices that apply to any GraphQL client library, including Apollo Client, urql, Relay, and others.
Does this skill include code generation or type safety setup?
The skill mentions type generation and linting as areas it addresses, with references to a tooling documentation file, but focuses primarily on writing and organizing operations by hand.
Can I use this skill for subscriptions?
Yes. The skill covers queries, mutations, and subscriptions equally, with examples and naming conventions for each.
Does this skill help optimize data fetching?
Yes. It includes principles like requesting only the fields you need, using fragments to avoid duplication, and leveraging directives like @include and @skip for conditional fetching.

Generated from the current SKILL.md. These answers refresh after source changes.