Encode GraphQL schema patterns into reusable Claude skills

A skill for GraphQL query/mutation patterns and code generation with Apollo Client. Four core rules: never write inline gql template literals - create .gql files instead; always run codegen after creating or modifying a .gql file; always attach an onError handler to mutations; and always use the generated hooks, never raw Apollo useQuery/useMutation. Queries follow a three-step flow: write a .gql file (e.g. GetItems.gql with typed variables), run npm run gql:typegen to produce a GetItems.generated.ts (never hand-edited), then import and use the generated useGetItemsQuery hook, checking error/loading/empty states explicitly before rendering data. Mutations follow the same flow but every trigger must meet four requirements: disabled during the mutation (prevents double-clicks), a visible loading state, a required onError handler so the user knows about failure, and success feedback on completion - shown via a documented complete pattern combining isDisabled/isLoading on the button with onError and onCompleted toasts. Query options cover four fetch policies (cache-first for rarely-changing data, cache-and-network as the fast-plus-fresh default, network-only for always-latest data, no-cache for the rare case of never caching) plus common options like notifyOnNetworkStatusChange, skip for conditional queries, and pollInterval for periodic refetching. Optimistic updates provide instant UI feedback via optimisticResponse, with automatic rollback on error - but are explicitly not for operations that can fail validation, have server-generated values, are destructive (delete), or affect other users. Reusable field selections use named fragments (e.g. a shared ItemFields fragment spread into multiple queries). Documented anti-patterns show the wrong-vs-right side by side: inline gql instead of a generated hook, a mutation with no error handler, and a submit button that stays enabled/unlabeled during a pending mutation. Two codegen commands are documented: npm run gql:typegen (generate types from existing .gql files) and npm run sync-types (download the schema and generate types). This skill integrates with react-ui-patterns for loading/error/empty states, testing-patterns for mocking generated hooks in tests, and formik-patterns for mutation submission.

Use it when creating GraphQL queries or mutations, working with Apollo Client, or generating types from a GraphQL schema.

Given a GraphQL operation need, it produces a .gql file plus the codegen command to run, and the resulting generated hook usage with required loading/error/empty-state handling and, for mutations, the mandatory disabled/loading/onError/success pattern.

npm run gql:typegen
npm run sync-types

Apollo Client with GraphQL code generation - generated hooks, fragments, cache.modify for manual cache updates, and optimisticResponse for instant UI feedback with automatic error rollback.

Frontend developers working with Apollo Client and GraphQL who want consistent, type-safe query and mutation patterns - generated hooks instead of inline gql, mandatory error handling on every mutation trigger, and clear guidance on when optimistic updates are and aren't appropriate.