Encode GraphQL schema patterns into reusable Claude skills

GraphQL Schema Patterns guides queries, mutations, fragments, and generated types in an Apollo Client application. Operations live in separate .gql files rather than inline gql literals. Changes to those operation files are followed by code generation, and components import generated hooks instead of handwritten raw Apollo hooks. Generated files remain generated artifacts rather than a place for manual edits.

The workflow separates component-local queries from shared mutations and reusable field selections. A query defines its variables and fields, then its generated hook exposes data, loading, error, and refetch behavior. Error rendering includes a retry path; the initial loading state differs from refreshing existing data, and an empty result gets its own interface state.

Use the skill when adding GraphQL operations, consuming them in a component, selecting a fetch strategy, or maintaining the associated generated types. The .gql layout, hook naming, and npm scripts are project conventions, so first confirm the actual schema, codegen configuration, and installed client version. A fragment that references unbundled UI components or helpers is not a complete application.

Optimistic updates are appropriate only when the anticipated result is safe to display immediately. Avoid them for operations that may fail validation, require server-generated values, delete data, or affect other users. Errors still need handling even when Apollo rolls an optimistic cache change back automatically.

Inputs include the schema, requested operation, variable types, reusable fields, current codegen setup, and component state requirements. Outputs include .gql definitions, regenerated TypeScript artifacts, generated-hook integration, and deliberate success, failure, loading, and empty states. An illustrative project generation command is:

npm run gql:typegen

The separate sync-types script combines schema downloading with type generation. Check that either script exists and targets the intended schema before execution. Query options include variables, conditional skipping, network-status notifications, and polling when updates are required.

Every mutation needs an onError handler and success feedback through onCompleted or an equivalent completed-state path. Its trigger is disabled during execution and shows loading feedback, preventing duplicate clicks while communicating progress. Cache updates require review against the installed Apollo cache API: normalize a newly returned entity rather than blindly appending a raw object in cache.modify.

Fetch policies express distinct freshness choices. The cache-first policy suits rarely changing data; explicitly selected cache-and-network combines cached display with a network request. The network-only policy requests current data, while no-cache avoids storing the result. Choose the policy deliberately rather than assuming the same default fits every query.

Reusable fragments centralize repeated field selections. Companion patterns address query loading/error/empty states, form submission, and tests that consume generated hooks. The skill connects operation definitions to application feedback and cache behavior; schema correctness, helper availability, and the real component environment still determine whether the resulting code works.