{"id":"eec1eadd-16c5-49a2-8c87-57ea21515e8c","shortId":"2saN9Q","kind":"skill","title":"graphql-operations","tagline":"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","description":"# GraphQL Operations Guide\n\nThis guide covers best practices for writing GraphQL operations (queries, mutations, subscriptions) as a client developer. Well-written operations are efficient, type-safe, and maintainable.\n\n## Operation Basics\n\n### Query Structure\n\n```graphql\nquery GetUser($id: ID!) {\n  user(id: $id) {\n    id\n    name\n    email\n  }\n}\n```\n\n### Mutation Structure\n\n```graphql\nmutation CreatePost($input: CreatePostInput!) {\n  createPost(input: $input) {\n    id\n    title\n    createdAt\n  }\n}\n```\n\n### Subscription Structure\n\n```graphql\nsubscription OnMessageReceived($channelId: ID!) {\n  messageReceived(channelId: $channelId) {\n    id\n    content\n    sender {\n      id\n      name\n    }\n  }\n}\n```\n\n## Quick Reference\n\n### Operation Naming\n\n| Pattern      | Example                                     |\n| ------------ | ------------------------------------------- |\n| Query        | `GetUser`, `ListPosts`, `SearchProducts`    |\n| Mutation     | `CreateUser`, `UpdatePost`, `DeleteComment` |\n| Subscription | `OnMessageReceived`, `OnUserStatusChanged`  |\n\n### Variable Syntax\n\n```graphql\n# Required variable\nquery GetUser($id: ID!) { ... }\n\n# Optional variable with default\nquery ListPosts($first: Int = 20) { ... }\n\n# Multiple variables\nquery SearchPosts($query: String!, $status: PostStatus, $first: Int = 10) { ... }\n```\n\n### Fragment Syntax\n\n```graphql\n# Define fragment\nfragment UserBasicInfo on User {\n  id\n  name\n  avatarUrl\n}\n\n# Use fragment\nquery GetUser($id: ID!) {\n  user(id: $id) {\n    ...UserBasicInfo\n    email\n  }\n}\n```\n\n### Directives\n\n```graphql\nquery GetUser($id: ID!, $includeEmail: Boolean!) {\n  user(id: $id) {\n    id\n    name\n    email @include(if: $includeEmail)\n  }\n}\n\nquery GetPosts($skipDrafts: Boolean!) {\n  posts {\n    id\n    title\n    draft @skip(if: $skipDrafts)\n  }\n}\n```\n\n## Key Principles\n\n### 1. Request Only What You Need\n\n```graphql\n# Good: Specific fields\nquery GetUserName($id: ID!) {\n  user(id: $id) {\n    id\n    name\n  }\n}\n\n# Avoid: Over-fetching\nquery GetUser($id: ID!) {\n  user(id: $id) {\n    id\n    name\n    email\n    bio\n    posts {\n      id\n      title\n      content\n      comments {\n        id\n      }\n    }\n    followers {\n      id\n      name\n    }\n    # ... many unused fields\n  }\n}\n```\n\n### 2. Name All Operations\n\n```graphql\n# Good: Named operation\nquery GetUserPosts($userId: ID!) {\n  user(id: $userId) {\n    posts {\n      id\n      title\n    }\n  }\n}\n\n# Avoid: Anonymous operation\nquery {\n  user(id: \"123\") {\n    posts {\n      id\n      title\n    }\n  }\n}\n```\n\n### 3. Use Variables, Not Inline Values\n\n```graphql\n# Good: Variables\nquery GetUser($id: ID!) {\n  user(id: $id) {\n    id\n    name\n  }\n}\n\n# Avoid: Hardcoded values\nquery {\n  user(id: \"123\") {\n    id\n    name\n  }\n}\n```\n\n### 4. Colocate Fragments with Components\n\n```tsx\n// UserAvatar.tsx\nexport const USER_AVATAR_FRAGMENT = gql`\n  fragment UserAvatar on User {\n    id\n    name\n    avatarUrl\n  }\n`;\n\nfunction UserAvatar({ user }) {\n  return <img src={user.avatarUrl} alt={user.name} />;\n}\n```\n\n## Reference Files\n\nDetailed documentation for specific topics:\n\n- [Queries](references/queries.md) - Query patterns and optimization\n- [Mutations](references/mutations.md) - Mutation patterns and error handling\n- [Fragments](references/fragments.md) - Fragment organization and reuse\n- [Variables](references/variables.md) - Variable usage and types\n- [Tooling](references/tooling.md) - Code generation and linting\n\n## Ground Rules\n\n- ALWAYS name your operations (no anonymous queries/mutations)\n- ALWAYS use variables for dynamic values\n- ALWAYS request only the fields you need\n- ALWAYS include `id` field for cacheable types\n- NEVER hardcode values in operations\n- NEVER duplicate field selections across files\n- PREFER fragments for reusable field selections\n- PREFER colocating fragments with components\n- USE descriptive operation names that reflect purpose\n- USE `@include`/`@skip` for conditional fields","tags":["graphql","operations","skills","apollographql","agent-skills","apollo"],"capabilities":["skill","source-apollographql","skill-graphql-operations","topic-agent-skills","topic-apollo","topic-graphql"],"categories":["skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/apollographql/skills/graphql-operations","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add apollographql/skills","source_repo":"https://github.com/apollographql/skills","install_from":"skills.sh"}},"qualityScore":"0.727","qualityRationale":"deterministic score 0.73 from registry signals: · indexed on github topic:agent-skills · official publisher · 53 github stars · SKILL.md body (3,924 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-04-23T06:56:10.973Z","embedding":null,"createdAt":"2026-04-18T20:31:33.064Z","updatedAt":"2026-04-23T06:56:10.973Z","lastSeenAt":"2026-04-23T06:56:10.973Z","tsv":"'1':19,214 '10':160 '123':284,312 '2':25,260 '20':149 '3':30,288 '4':35,315 'across':420 'alt':342 'alway':384,391,397,404 'anonym':279,389 'avatar':325 'avatarurl':172,334 'avoid':233,278,306 'basic':73 'best':13,48 'bio':247 'boolean':191,204 'cacheabl':409 'channelid':105,108,109 'client':59 'code':378 'coloc':316,429 'comment':252 'compon':319,432 'condit':444 'const':323 'content':111,251 'cover':47 'createdat':99 'createpost':91,94 'createpostinput':93 'createus':126 'data':32 'default':144 'defin':164 'deletecom':128 'descript':434 'detail':346 'develop':60 'direct':184 'document':347 'draft':208 'duplic':417 'dynam':395 'effici':66 'email':86,183,197,246 'error':362 'exampl':120 'export':322 'fetch':33,236 'field':223,259,401,407,418,426,445 'file':345,421 'first':147,158 'follow':12,254 'fragment':11,29,161,165,166,174,317,326,328,364,366,423,430 'function':335 'generat':39,379 'getpost':202 'getus':78,122,138,176,187,238,298 'getusernam':225 'getuserpost':269 'good':221,265,295 'gql':327 'graphql':2,7,21,42,52,76,89,102,134,163,185,220,264,294 'graphql-oper':1 'ground':382 'guid':4,44,46 'handl':363 'hardcod':307,412 'id':79,80,82,83,84,97,106,110,113,139,140,170,177,178,180,181,188,189,193,194,195,206,226,227,229,230,231,239,240,242,243,244,249,253,255,271,273,276,283,286,299,300,302,303,304,311,313,332,406 'img':339 'includ':198,405,441 'includeemail':190,200 'inlin':292 'input':92,95,96 'int':148,159 'key':212 'lint':41,381 'listpost':123,146 'maintain':71 'mani':257 'messagereceiv':107 'multipl':150 'mutat':10,24,55,87,90,125,357,359 'name':85,114,118,171,196,232,245,256,261,266,305,314,333,385,436 'need':219,403 'never':411,416 'onmessagereceiv':104,130 'onuserstatuschang':131 'oper':3,8,27,43,53,64,72,117,263,267,280,387,415,435 'optim':31,356 'option':141 'organ':26,367 'over-fetch':234 'pattern':34,119,354,360 'post':205,248,275,285 'poststatus':157 'practic':14,49 'prefer':422,428 'principl':213 'purpos':439 'queri':9,22,54,74,77,121,137,145,152,154,175,186,201,224,237,268,281,297,309,351,353 'queries/mutations':390 'quick':115 'refer':116,344 'references/fragments.md':365 'references/mutations.md':358 'references/queries.md':352 'references/tooling.md':377 'references/variables.md':371 'reflect':438 'request':215,398 'requir':135 'return':338 'reus':369 'reusabl':425 'rule':383 'safe':69 'searchpost':153 'searchproduct':124 'select':419,427 'sender':112 'set':36 'skill':17 'skill-graphql-operations' 'skip':209,442 'skipdraft':203,211 'source-apollographql' 'specif':222,349 'src':340 'status':156 'string':155 'structur':75,88,101 'subscript':56,100,103,129 'syntax':133,162 'titl':98,207,250,277,287 'tool':376 'topic':350 'topic-agent-skills' 'topic-apollo' 'topic-graphql' 'tsx':320 'type':38,68,375,410 'type-saf':67 'unus':258 'updatepost':127 'usag':373 'use':15,173,289,392,433,440 'user':81,169,179,192,228,241,272,282,301,310,324,331,337 'user.avatarurl':341 'user.name':343 'useravatar':329,336 'useravatar.tsx':321 'userbasicinfo':167,182 'userid':270,274 'valu':293,308,396,413 'variabl':132,136,142,151,290,296,370,372,393 'well':62 'well-written':61 'write':6,20,51 'written':63","prices":[{"id":"1c4a710a-a86a-47d5-9ce7-96cbdc05506a","listingId":"eec1eadd-16c5-49a2-8c87-57ea21515e8c","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"apollographql","category":"skills","install_from":"skills.sh"},"createdAt":"2026-04-18T20:31:33.064Z"}],"sources":[{"listingId":"eec1eadd-16c5-49a2-8c87-57ea21515e8c","source":"github","sourceId":"apollographql/skills/graphql-operations","sourceUrl":"https://github.com/apollographql/skills/tree/main/skills/graphql-operations","isPrimary":false,"firstSeenAt":"2026-04-18T22:17:26.144Z","lastSeenAt":"2026-04-23T06:56:10.973Z"},{"listingId":"eec1eadd-16c5-49a2-8c87-57ea21515e8c","source":"skills_sh","sourceId":"apollographql/skills/graphql-operations","sourceUrl":"https://skills.sh/apollographql/skills/graphql-operations","isPrimary":true,"firstSeenAt":"2026-04-18T20:31:33.064Z","lastSeenAt":"2026-04-23T06:40:29.376Z"}],"details":{"listingId":"eec1eadd-16c5-49a2-8c87-57ea21515e8c","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"apollographql","slug":"graphql-operations","github":{"repo":"apollographql/skills","stars":53,"topics":["agent-skills","apollo","graphql"],"license":"mit","html_url":"https://github.com/apollographql/skills","pushed_at":"2026-04-22T16:25:05Z","description":"Apollo GraphQL Agent Skills","skill_md_sha":"536902219b8633e0a883e0e979db67a5eed8bb51","skill_md_path":"skills/graphql-operations/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/apollographql/skills/tree/main/skills/graphql-operations"},"layout":"multi","source":"github","category":"skills","frontmatter":{"name":"graphql-operations","license":"MIT","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.","compatibility":"Any GraphQL client (Apollo Client, urql, Relay, etc.)"},"skills_sh_url":"https://skills.sh/apollographql/skills/graphql-operations"},"updatedAt":"2026-04-23T06:56:10.973Z"}}