graphql-mutations_skill

Overview

This skill provides focused guidance for designing and implementing GraphQL mutations with reliable payloads, field-specific errors, input objects, and correct HTTP semantics. It codifies practical patterns for naming, validation, idempotency, and async side effects so mutations are predictable and client-friendly. Use it to standardize mutation shapes across services and to avoid common pitfalls.

How this skill works

The skill inspects mutation design concerns: payload structure, input object usage, error reporting, naming conventions, and HTTP rules. It recommends always returning a payload type containing the result and an errors array, using input objects for complex arguments, and mapping validation and domain errors to field-specific errors in the payload. It also enforces POST-only semantics, idempotency guidance, and patterns for async operations (job IDs and status queries).

When to use it

• Designing a new mutation API or standardizing existing mutations
• Implementing server-side mutation resolvers in Go, Node, or similar
• Defining client-server contracts to support optimistic UI and validation
• Handling complex arguments or many fields that would make scalars unwieldy
• Adding robust error handling and field-level validation feedback

Best practices

• Always return a payload type (never a bare boolean or raw object)
• Use input objects for complex or nested arguments instead of many scalars
• Return field-specific errors in a structured errors array for client handling
• Name mutations with noun + verb (createUser, deletePost, closeCard)
• Design for idempotency and document non-obvious side effects
• Use POST for all mutations and avoid caching; expose no internal errors

Example use cases

• CreateUser mutation: input object, payload with user and errors for validation
• UpdateUser mutation: id plus input object and field errors for partial validation
• DeleteUser mutation: returns deletedUserId in payload and errors when not allowed
• CloseCard state change: noun+verb naming and payload with card and errors
• Async tasks: return jobId in payload and provide a query to check status