Design a GraphQL schema

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/design-graphql-schema/raw' -o ~/'.claude/skills/design-graphql-schema/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/design-graphql-schema/files/LICENSE.txt' -o ~/'.claude/skills/design-graphql-schema/LICENSE.txt'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/design-graphql-schema/raw' -o '.cursor/skills/design-graphql-schema/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/design-graphql-schema/files/LICENSE.txt' -o '.cursor/skills/design-graphql-schema/LICENSE.txt'

curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/design-graphql-schema/raw' -o '.agents/skills/design-graphql-schema/SKILL.md' && curl -fsSL --create-dirs 'https://theskillvault.ai/api/skills/design-graphql-schema/files/LICENSE.txt' -o '.agents/skills/design-graphql-schema/LICENSE.txt'

{
  "mcpServers": {
    "theskillvault": {
      "url": "https://theskillvault.ai/mcp"
    }
  }
}

A GraphQL schema is a promise to every client. Shape it around what screens ask for, not around your tables, and change it only in ways old clients survive.

When to use

• You are starting a GraphQL API and want the schema planned first.
• You are adding types, fields, arguments or mutations to an existing schema.
• You are unsure when a field should be nullable.
• You want a schema reviewed before a mobile or web client ships against it.

When not to use

• Your API is plain HTTP routes. Use design-rest-api.
• You need resolvers, a server or a client set up. This skill covers the schema contract only.

Steps

1. List the screens or jobs clients have, and the data each one needs.
2. Name types after domain ideas (Order, Customer), not storage (order_rows).
3. Give every type and field a description in """ quotes.
4. Use ID for identifiers and add custom scalars such as DateTime or URL for typed values.
5. Mark a field non-null (!) only when it can never fail to resolve. Lists are almost always [Item!]!.
6. Give each mutation one input argument and return the changed object, or a result union.
7. Paginate any list that can grow, using a connection with first (with a default) and after.
8. Use enums for fixed choices and interfaces or unions for shared or alternative shapes.
9. Model expected failures, such as "email taken", as typed results, not only as top-level errors.
10. Add a depth or cost limit and authorisation checks before you expose the schema publicly.

"""A customer who has placed at least one order."""
type Customer implements Node {
  id: ID!
  name: String!
  "Most recent first."
  orders(first: Int = 20, after: String): OrderConnection!
}

input PlaceOrderInput { customerId: ID!, items: [OrderItemInput!]!, note: String }

union PlaceOrderResult = PlaceOrderSuccess | OutOfStock | InvalidAddress

type Mutation {
  "Places an order. Expected problems come back as typed results."
  placeOrder(input: PlaceOrderInput!): PlaceOrderResult!
}

Changing a live schema safely

1. Add new fields and types freely. Adding is safe.
2. New arguments and input fields must be nullable or have a default, or old requests fail.
3. Mark old fields @deprecated(reason: "Use totalAmount") and wait until usage reaches zero.
4. Never rename, retype or make a field newly non-null in one step.

Gotchas

• A non-null field that errors nulls out its whole parent object. Overusing ! turns one bad field into a blank screen.
• Unpaginated lists look fine in testing and time out with real data.
• Exposing database columns one to one leaks internals and locks the schema to your tables.
• Turn off introspection or limit it in production if the API is private, and never put secrets or tokens in field descriptions or examples.
• Check permissions in resolvers or a shared layer, not by hiding fields from the schema.

Portability

Works with any GraphQL server: Apollo Server, GraphQL Yoga, graphql-js, Hot Chocolate, Strawberry or gqlgen. The same rules apply if you write code-first schemas instead of SDL files.

Example prompt

"Design the GraphQL schema for a recipe app with users, recipes and saved lists. Include pagination and the mutations for saving a recipe."

Done when

• Every type and field has a description, and every growing list is paginated.
• Mutations take one input and return the result or typed errors.
• Planned changes are additive or go through deprecation, and query limits are in place.

---

Adapted from "graphql-schema" in apollographql/skills (MIT, Copyright (c) 2024 Apollo Graph, Inc.). See LICENSE.txt.

Bundled files

• LICENSE.txt

Licence

Adapted from Apollo Graph, Inc. (apollographql/skills, graphql-schema) (Copyright (c) 2024 Apollo Graph, Inc.), MIT License. Adapted by TheSkillVault on 2026-11-02: rewritten as a design order with an original schema example and a change-safety checklist; reference files were not copied; added when-not-to-use, security and secrets notes, gotchas and done-when. Not the original file.

Licence: MIT License. Attribution when you reuse it: Based on work by Apollo Graph, Inc. (apollographql/skills, graphql-schema) (Copyright (c) 2024 Apollo Graph, Inc., MIT License), https://github.com/apollographql/skills/tree/9dda1397730370aeb8df4ff8f2015c34c86b5003/skills/graphql-schema; adapted by TheSkillVault, https://theskillvault.ai