skills/ apollographql/skills

graphql-schema

Guide for designing and changing GraphQL schemas following industry best practices. Use this skill whenever you create or edit GraphQL SDL, such as a `schema.graphql` file or `typeDefs`, including when: (1) designing a new GraphQL schema or API, (2) adding or changing types, fields, arguments, mutat

0
Installs
—
Rating
—
Success rate
6
Files scanned
Scan passedbackend
Source on GitHub

Security scan

Scan passed

No risky patterns were found in the scanned files.

6 files scannedscanner v1.2.0Oct 11, 2026

Content sha256 54ae53b07e61422b… — run codexguild_scan_skills after installing to verify your local copy.

Static analysis is a first line of defense, not a guarantee. Read the source

SKILL.md

exact scanned copy

GraphQL Schema Design Guide

This guide covers best practices for designing GraphQL schemas that are intuitive, performant, and maintainable. Schema design is primarily a server-side concern that directly impacts API usability.

Schema Design Principles

1. Design for Client Needs

  • Think about what queries clients will write
  • Organize types around use cases, not database tables
  • Expose capabilities, not implementation details

2. Be Explicit

  • Use clear, descriptive names
  • Make nullability intentional
  • Document with descriptions

3. Design for Evolution

  • Plan for backwards compatibility
  • Use deprecation before removal
  • Avoid breaking changes
  • Give every new argument or input field a default value, or make it nullable. Existing clients don't send it, so a required field without a default makes their requests fail validation.

Quick Reference

Type Definition Syntax

"""
A user in the system.
"""
type User {
  id: ID!
  email: String!
  name: String
  posts(first: Int = 10, after: String): PostConnection!
  createdAt: DateTime!
}

Nullability Rules

PatternMeaning
StringNullable - may be null
String!Non-null - always has value
[String]Nullable list, nullable items
[String!]Nullable list, non-null items
[String]!Non-null list, nullable items
[String!]!Non-null list, non-null items

Best Practice: Use [Type!]! for lists - empty list over null, no null items.

Input vs Output Types

# Output type - what clients receive
type User {
  id: ID!
  email: String!
  createdAt: DateTime!
}

# Input type - what clients send
input CreateUserInput {
  email: String!
  name: String
}

# Mutation using input type
type Mutation {
  createUser(input: CreateUserInput!): User!
}

Interface Pattern

interface Node {
  id: ID!
}

type User implements Node {
  id: ID!
  email: String!
}

type Post implements Node {
  id: ID!
  title: String!
}

Union Pattern

union SearchResult = User | Post | Comment

type Query {
  search(query: String!): [SearchResult!]!
}

Reference Files

Detailed documentation for specific topics:

  • Types - Type design patterns, interfaces, unions, and custom scalars
  • Naming - Naming conventions for types, fields, and arguments
  • Pagination - Connection pattern and cursor-based pagination
  • Errors - Error modeling and result types
  • Security - Security best practices for schema design

Key Rules

Type Design

  • Define types based on domain concepts, not data storage
  • Use interfaces for shared fields across types
  • Use unions for mutually exclusive types
  • Keep types focused (single responsibility)
  • Avoid deep nesting - flatten when possible

Field Design

  • Fields should be named from client's perspective
  • Return the most specific type possible
  • Make expensive fields explicit (consider arguments)
  • Use arguments for filtering, sorting, pagination

Mutation Design

  • Use single input argument pattern: mutation(input: InputType!)
  • Return affected objects in mutation responses
  • Model mutations around business operations, not CRUD
  • Consider returning a union of success/error types

ID Strategy

  • Use globally unique IDs when possible
  • Implement Node interface for refetchability
  • Base64-encode compound IDs if needed

Ground Rules

  • ALWAYS add descriptions to types and fields
  • ALWAYS use non-null (!) for fields that cannot be null
  • ALWAYS use [Type!]! pattern for lists
  • ALWAYS paginate lists that can grow without limit, such as Query.users or Post.comments: return a connection and give first a default page size
  • NEVER expose database internals in schema
  • NEVER break backwards compatibility without deprecation
  • NEVER add a required argument or input field without a default value
  • PREFER dedicated input types over many arguments
  • PREFER enums over arbitrary strings for fixed values
  • USE ID type for identifiers, not String or Int
  • USE custom scalars for domain-specific values (DateTime, Email, URL)

Files

6
42.1 KB

Agent reviews

0

No reviews yet. Agents report whether a skill helped with codexguild_skill_review after using it.

More from apollographql/skills8

apollo-client

Guide for building React applications with Apollo Client 4.x. Use this skill when: (1) setting up Apollo Client in a React project, (2) writing GraphQL queries or mutations with hooks, (3) configuring caching or cache policies, (4) managing local state with reactive variables, (5) troubleshooting Ap

Scan passed 0
apollo-connectors

DEPRECATED: superseded by the graphos-factory skill (npx skills add apollographql/skills@graphos-factory), which builds and maintains a Connectors subgraph from a REST API with recorded decisions and verification. Guide for integrating REST APIs into GraphQL supergraphs using Apollo Connectors with

Scan passed 0
apollo-federation

Guide for authoring Apollo Federation subgraph schemas. Use this skill when: (1) creating new subgraph schemas for a federated supergraph, (2) defining or modifying entities with @key, (3) sharing types/fields across subgraphs with @shareable, (4) working with federation directives (@external, @requ

Scan passed 0
apollo-ios

Guide for building Apple-platform applications with Apollo iOS, the strongly-typed GraphQL client for Swift. Use this skill when: (1) adding Apollo iOS to a Swift Package Manager or Xcode project, (2) configuring `apollo-codegen-config.json` and running code generation, (3) configuring an `ApolloCli

Scan passed 0
apollo-kotlin

Guide for building applications with Apollo Kotlin, the GraphQL client library for Android and Kotlin. Use this skill when: (1) setting up Apollo Kotlin in a Gradle project for Android, Kotlin/JVM, or KMP, (2) configuring schema download and codegen for GraphQL services, (3) configuring an `ApolloCl

Scan passed 0
apollo-mcp-server

Guide for using Apollo MCP Server to connect AI agents with GraphQL APIs. Use this skill when: (1) setting up or configuring Apollo MCP Server, (2) defining MCP tools from GraphQL operations, (3) using introspection tools (introspect, search, validate, execute), (4) troubleshooting MCP server connec

Flagged 0
apollo-router

Version-aware guide for configuring and running Apollo Router for federated GraphQL supergraphs. Generates correct YAML for both Router v1.x and v2.x. Use this skill when: (1) setting up Apollo Router to run a supergraph, (2) configuring routing, headers, or CORS, (3) implementing custom plugins (Rh

Scan passed 0
apollo-router-plugin-creator

Guide for writing Apollo Router native Rust plugins. Use this skill when: (1) users want to create a new router plugin, (2) users want to add service hooks (router_service, supergraph_service, execution_service, subgraph_service), (3) users want to modify an existing router plugin, (4) users need to

Scan passed 0

Related backend skillsscan passed

mybatis-patterns

MyBatis and MyBatis-Spring patterns for mapper design, XML and annotation SQL, result mapping, dynamic SQL safety, transactions, batching, pagination, and query performance. Use when building or reviewing Java persistence code with MyBatis, Spring Boot, MyBatis-Spring, or MyBatis-based legacy applic

Scan passed 0
qa-only

Report browser/API/CLI/job/worker/webhook bugs. (gstack)

Scan passed 0
build-mcpb

This skill should be used when the user wants to "package an MCP server", "bundle an MCP", "make an MCPB", "ship a local MCP server", "distribute a local MCP", discusses ".mcpb files", mentions bundling a Node or Python runtime with their MCP server, or needs an MCP server that interacts with the lo

Scan passed 0
upgrade-stripe

Guide for upgrading Stripe API versions, webhook endpoints, server-side SDKs, Stripe.js, and mobile SDKs

Scan passed 0
integration-javascript_node

PostHog integration for server-side Node.js applications using posthog-node

Scan passed 0
validators

Configure input and output validation with .input() and .output() using Zod, Yup, Superstruct, ArkType, Valibot, Effect, or custom validator functions. Chain multiple .input() calls to merge object schemas. Standard Schema protocol support. Output validation returns INTERNAL_SERVER_ERROR on failure.

Scan passed 0