graphql-schema

Design GraphQL schemas with best practices for types, naming, and pagination.

102|12|Updated Jan 23, 2026
One-click install
npx skills add https://github.com/apollographql/skills --skill graphql-schema-apollographql
Or copy as Structured Prompt for Agent
Please help me install this Agent Skill.
Skill: graphql-schema
Source: https://github.com/apollographql/skills/tree/main/skills/graphql-schema
Command: npx skills add https://github.com/apollographql/skills --skill graphql-schema-apollographql

SYSTEM DOCUMENTATION & REQUIREMENTS

💡 This Skill includes references (resource) components.

What problem does it solve?

This Skill helps you design GraphQL schemas that are easy for clients to use, performant, and maintainable, avoiding common pitfalls in API design.

Core Features & Use Cases

  • Schema Design Principles: Learn best practices for organizing types, naming conventions, and handling nullability.
  • Type Patterns: Understand how to use interfaces, unions, and custom scalars effectively.
  • Error & Pagination: Implement robust error handling and cursor-based pagination.
  • Use Case: You are designing a new GraphQL API for a social media platform. Use this Skill to define clear User, Post, and Comment types, implement a Node interface for refetching, and establish a consistent error handling strategy for mutations.

Quick Start

Review the best practices for naming conventions in GraphQL schema design.

Frequently Asked Questions about graphql-schema

High-intent search queries and answers about installing and using this skill.

FAQPage Schema
What are the best practices for GraphQL schema design and naming conventions?

GraphQL schema design best practices involve organizing types with clear naming conventions, handling nullability appropriately, and using interfaces for refetching to ensure APIs are intuitive, performant, and maintainable. This guidance helps avoid common API design pitfalls.

How do I implement cursor-based pagination and error handling in a GraphQL schema?

Implement cursor-based pagination and robust error handling in a GraphQL schema by following established patterns for connections and mutation errors. This ensures clients can reliably fetch large datasets and process mutation failures gracefully.

When should I use interfaces versus unions in a GraphQL type system?

Use interfaces in a GraphQL type system when multiple types share common fields like a Node interface for refetching, and use unions when types return disparate fields. This distinction ensures flexible, predictable queries for clients.

How do I structure input types, enums, and custom scalars for a GraphQL API?

Structure input types, enums, and custom scalars in a GraphQL API by applying principles for type design that prioritize clarity and performance. Properly structured types make mutations safer and data validation more consistent.

What security considerations should I follow when designing a GraphQL schema?

Security considerations for GraphQL schema design include implementing patterns to prevent malicious queries and managing access control. Following these guidelines protects your API from vulnerabilities while maintaining schema performance.