Publish Sign in
Expertise·API Development·v1.0.1

GraphQL Schema

Guide for designing GraphQL schemas following industry best practices: type structure, nullability, pagination, error patterns and schema…

You say
Buy it · $35 Read it before you buy $35 Written by apollographql · unverified publisher
Context cost
10.6k tokensestimated from the bundle, loaded when it triggers
Bundle
6 files · 42.5 kBtext throughout, nothing executable
Licence
MITpaid listing
Last change
—v1.0.1
Servers it uses
Noneruns standalone

What it does

Guide for designing GraphQL schemas following industry best practices. Use this skill when: (1) designing a new GraphQL schema or API, (2) reviewing existing schema for improvements, (3) deciding on type structures or nullability, (4) implementing pagination or error patterns, (5) ensuring security in schema design.

Installed, it changes the agent in these ways.

What this skill changes about the agent is not written down here yet. The listing was collected from its source, and the description is in its own SKILL.md.

Expertise

Domain judgement the base model does not have.

graphqlschemaapi-design
Filed under

API Development

The skill itself

This is the whole product. A skill is instructions the model reads, so there is nothing behind the listing you cannot see first — the front matter loads with every session, and the body below it loads when the skill triggers.

SKILL.md4.4 kB · 173 lines
--- name: graphql-schema description: > Guide for designing GraphQL schemas following industry best practices. Use this skill when: (1) designing a new GraphQL schema or API, (2) reviewing existing schema for improvements, (3) deciding on type structures or nullability, (4) implementing pagination or error patterns, (5) ensuring security in schema design. license: MIT compatibility: Any GraphQL implementation (Apollo Server, graphql-js, Yoga, etc.) metadata: author: apollographql version: "1.0.1" allowed-tools: Bash(npm:*) Bash(npx:*) Read Write Edit Glob Grep ---
18# GraphQL Schema Design Guide
19
20This guide covers best practices for designing GraphQL schemas that are intuitive, performant, and maintainable. Schema design is primarily a server-side concern that directly impacts API usability.
21
22## Schema Design Principles
23
24### 1. Design for Client Needs
25
26- Think about what queries clients will write
27- Organize types around use cases, not database tables
28- Expose capabilities, not implementation details
29
30### 2. Be Explicit
31
32- Use clear, descriptive names
33- Make nullability intentional
34- Document with descriptions
35
36### 3. Design for Evolution
37
38- Plan for backwards compatibility
39- Use deprecation before removal
40- Avoid breaking changes
41
42## Quick Reference
43
44### Type Definition Syntax
45
46```graphql
47"""
48A user in the system.
49"""
50type User {
51 id: ID!
52 email: String!
53 name: String
54 posts(first: Int = 10, after: String): PostConnection!
55 createdAt: DateTime!
56}
57```
58
59### Nullability Rules
60
61| Pattern | Meaning |
62|---------|---------|
63| String | Nullable - may be null |
64| String! | Non-null - always has value |
65| [String] | Nullable list, nullable items |
66| [String!] | Nullable list, non-null items |
67| [String]! | Non-null list, nullable items |
68| [String!]! | Non-null list, non-null items |
69
70**Best Practice:** Use **[Type!]!** for lists - empty list over null, no null items.
71
72### Input vs Output Types
73
74```graphql
75# Output type - what clients receive
76type User {
77 id: ID!
78 email: String!
79 createdAt: DateTime!
80}
81
82# Input type - what clients send
83input CreateUserInput {
84 email: String!
85 name: String
86}
87
88# Mutation using input type
89type Mutation {
90 createUser(input: CreateUserInput!): User!
91}
92```
93
94### Interface Pattern
95
96```graphql
97interface Node {
98 id: ID!
99}
100
101type User implements Node {
102 id: ID!
103 email: String!
104}
105
106type Post implements Node {
107 id: ID!
108 title: String!
109}
110```
111
112### Union Pattern
113
114```graphql
115union SearchResult = User | Post | Comment
116
117type Query {
118 search(query: String!): [SearchResult!]!
119}
120```
121
122## Reference Files
123
124Detailed documentation for specific topics:
125
126- [Types](references/types.md) - Type design patterns, interfaces, unions, and custom scalars
127- [Naming](references/naming.md) - Naming conventions for types, fields, and arguments
128- [Pagination](references/pagination.md) - Connection pattern and cursor-based pagination
129- [Errors](references/errors.md) - Error modeling and result types
130- [Security](references/security.md) - Security best practices for schema design
131
132## Key Rules
133
134### Type Design
135
136- Define types based on domain concepts, not data storage
137- Use interfaces for shared fields across types
138- Use unions for mutually exclusive types
139- Keep types focused (single responsibility)
140- Avoid deep nesting - flatten when possible
141
142### Field Design
143
144- Fields should be named from client's perspective
145- Return the most specific type possible
146- Make expensive fields explicit (consider arguments)
147- Use arguments for filtering, sorting, pagination
148
149### Mutation Design
150
151- Use single input argument pattern: mutation(input: InputType!)
152- Return affected objects in mutation responses
153- Model mutations around business operations, not CRUD
154- Consider returning a union of success/error types
155
156### ID Strategy
157
158- Use globally unique IDs when possible
159- Implement Node interface for refetchability
160- Base64-encode compound IDs if needed
161
162## Ground Rules
163
164- ALWAYS add descriptions to types and fields
165- ALWAYS use non-null (**!**) for fields that cannot be null
166- ALWAYS use **[Type!]!** pattern for lists
167- NEVER expose database internals in schema
168- NEVER break backwards compatibility without deprecation
169- PREFER dedicated input types over many arguments
170- PREFER enums over arbitrary strings for fixed values
171- USE ID type for identifiers, not String or Int
172- USE custom scalars for domain-specific values (DateTime, Email, URL)
173
In the file
SKILL.md654 words
Files6
LicenceMIT
Why you can read it

Nothing in a skill executes. The client loads the text and the model follows it, so a skill can be audited the way a runbook is — by reading it.

What it costs in context

Skills are not billed by the call. They are paid for in context: every token the instructions occupy is a token your code, your diff and your conversation cannot use. Here is what this one takes and when it takes it.

≈150
always loaded
The name and description, so the model knows the skill exists and when to reach for it.
10,475
on trigger
The instruction body and 5 supporting files, read only when the skill fires.
5.3%
of a 200k window
Ten skills this size would take about 53% of the window before you open a file.
050k100k150k200k context window

10.6k tokens, estimated from the bundle at four bytes to the token, held for the rest of the session once it triggers. Heavy. Teams tend to install this one per project rather than globally, and load it only when the job comes up.

Servers bill, skills cost

A server charges by the month. A skill charges once per session, in context, and then keeps charging it for as long as the session lives.

Before and after

The same question, put to the same model twice: once as it comes, and once with these instructions loaded.

No worked example has been published for this skill yet.

Adoption
Installsnone yet
Ratingno reviews yet

The procedure it runs

The procedure has not been published here. It is in the skill’s own SKILL.md, which its author has not sent to the marketplace yet.

Prose, not code

These steps are written for a model to follow, not executed by a runtime. It can still be told to skip one, and it will say so when it does.

Servers it uses

None. This skill calls no MCP servers at all.

Everything it needs is in the instructions, so it works in a project with nothing connected — the model reads the file and changes how it works with what it can already reach.

It asks the agent to write files, using whatever file access your client already has. It never touches the network.

What it asks for
Writes filesyes
Network accessno

Read from the allowed-tools line of this skill’s own SKILL.md. A skill grants no permissions of its own — it can only ask for tools your client already has.

What it will not do

Every skill is narrow, and the useful ones say where they stop. These are the jobs this one is the wrong tool for.

What this skill is not for has not been published here. Nothing is implied by that: it is a section the author has not filled in.

What is in the bundle

6 files, 42.5 kB on disk. A bundle is text throughout: the instructions the model reads, plus the templates it fills in.

  • SKILL.md4.4 kB
  • references/errors.md6.7 kB
  • references/naming.md6.8 kB
  • references/pagination.md7.2 kB
  • references/security.md9.4 kB
  • references/types.md8.0 kB
What is not in it

No dependencies and nothing executable: a skill is text the agent reads, so the bundle is 6 files you can review in full before installing. The MIT licence covers the templates and examples as well as the instructions.

Install

Installing copies the bundle into your project. Nothing runs at install time — the files sit on disk until the model reads them.

$35 once
GraphQL Schema · MIT · apollographql
one-time
Price$35 once
LicenceMIT — the author’s, unchanged by this purchase
Paid throughStripe, once, on the card you add at the checkout
Keeps workingfor good — the files are yours once they are on disk
Updatesevery release of 1.x through this account

You can read the whole bundle before paying — the SKILL.md above is the product, not a preview of it. What the money buys is the delivery: the folder packaged and handed to your machine by key, every update its author ships, and our support if it does not do what this listing says. The terms of use are MIT, set by the author and unchanged by buying it here.

Sign in to buyCreate an account

Payment runs through Stripe, on a page like this one rather than a redirect. Once there is an account it joins the same mcprush invoice as everything else you run, so there is never a second card to enter.

Which clients pick it up on their own

A skill is a folder of text. A client with a skills folder reads it without being told; everywhere else the same text works, it is just handed to the model rather than found.

Claude Code.claude/skills/
Claude Desktop
ChatGPT
Cursor.cursor/skills/
VS Code.github/skills/
Codex CLI.agents/skills/
Gemini CLI.gemini/skills/
Grok.grok/skills/
Zed.agents/skills/
Windsurf.windsurf/skills/
Agent SDK.claude/skills/
HTTP / API
This release
Version1.0.1
Publishedno release date on file
Price$35
Referenceapollographql/graphql-schema

Versions

v1.0.1 is what is on the shelf; no release here carries a date. Instructions change more often than APIs do — a skill can be rewritten entirely without anything it depends on moving.

v1.0.1
  • No earlier releases have been published to the marketplace.
Pinning

Put apollographql/graphql-schema@1.0.1 in the install command to hold this exact version. Without the suffix you get whatever is current the day you install, and nothing moves under you afterwards.

Reviews

—no reviews yet · no installs yet

Nobody has reviewed this skill yet. The rating is the mean of the reviews written here, so there is none until somebody writes the first.

Who can post

Only accounts that have had the skill installed for fourteen days, so a review is written after living with it rather than after reading it. Publishers may reply once.

Who wrote it

AP
apollographql

Publishes on mcprush.

0 servers listed4 skills listednot claimed
Profile
Publisher
Servers0