graphql-operations
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.
- License 许可
- MIT
- 最近更新
- 2026-11-13
- Stars
- ★ 29
- Forks
- 156
01 前言 Front Matter
- name
- graphql-operations
- license
- MIT
- metadata
- { "author": "apollographql", "version": "1.0.0" }
- description
- 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.
- allowed-tools
- Bash(npm:*) Bash(npx:*) Read Write Edit Glob Grep
- compatibility
- Any GraphQL client (Apollo Client, urql, Relay, etc.)
02 资源文件 5
- 参考文档references/fragments.md7.5 KB
- 参考文档references/mutations.md7.7 KB
- 参考文档references/queries.md7.7 KB
- 参考文档references/tooling.md8.3 KB
- 参考文档references/variables.md6.4 KB
03 SKILL.md 正文
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.
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 name your operations (no anonymous queries/mutations)
- ALWAYS use variables for dynamic values
- ALWAYS request only the fields you need
- ALWAYS include
idfield 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/@skipfor conditional fields
04 同仓库更多 Skills
business-data
暂无简介
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.
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.
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.
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.
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`.