AGENT SKILL

graphql-schema

Guide for designing GraphQL schemas following industry best practices. Use this skill when: (1) designing a new GraphQL schema or API, (2) reviewing existing schema for improvements, (3) deciding on type structures or nullability, (4) implementing pagination or error patterns, (5) ensuring security in schema design.

License 许可
MIT
最近更新
2026-11-13
Stars
★ 29
Forks
156

01 前言 Front Matter

name
graphql-schema
license
MIT
metadata
{ "author": "apollographql", "version": "1.0.1" }
description
Guide for designing GraphQL schemas following industry best practices. Use this skill when: (1) designing a new GraphQL schema or API, (2) reviewing existing schema for improvements, (3) deciding on type structures or nullability, (4) implementing pagination or error patterns, (5) ensuring security in schema design.
allowed-tools
Bash(npm:*) Bash(npx:*) Read Write Edit Glob Grep
compatibility
Any GraphQL implementation (Apollo Server, graphql-js, Yoga, etc.)

02 资源文件 5

03 SKILL.md 正文

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

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

Pattern Meaning
String Nullable - 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
  • NEVER expose database internals in schema
  • NEVER break backwards compatibility without deprecation
  • 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)

04 同仓库更多 Skills

CognitionAI
CognitionAI/devin-marketplace

business-data

暂无简介

★ 29
CognitionAI
CognitionAI/devin-marketplace

workflow

Creates durable, resumable workflows using Vercel's Workflow SDK. Use when building workflows that need to survive restarts, pause for external events, retry on failure, or coordinate multi-step operations over time. Triggers on mentions of "workflow", "durable functions", "resumable", "workflow sdk", "queue", "event", "push", "subscribe", or step-based orchestration.

★ 29
CognitionAI
CognitionAI/devin-marketplace

workflow

Vercel Workflow SDK expert guidance. Use when building durable workflows, long-running tasks, API routes or agents that need pause/resume, retries, step-based execution, or crash-safe orchestration with Vercel Workflow.

★ 29
CognitionAI
CognitionAI/devin-marketplace

verification

Full-story verification — infers what the user is building, then verifies the complete flow end-to-end: browser → API → data → response. Triggers on dev server start and 'why isn't this working' signals.

★ 29
CognitionAI
CognitionAI/devin-marketplace

vercel-storage

Vercel storage expert guidance — Blob, Global Config (formerly Edge Config), and Marketplace storage (Neon Postgres, Upstash Redis). Use when choosing, configuring, or using data storage with Vercel applications.

★ 29
CognitionAI
CognitionAI/devin-marketplace

vercel-services

Configure and troubleshoot Vercel Services for multiple frontends and backends in one project. Use when composing a polyglot or multi-service application on one Vercel deployment; defining the `services` key, service-targeted rewrites, or service bindings in `vercel.json`; or running all services with `vercel dev`.

★ 29