---
name: graphql-schema-documenter
description: "A docs-folder-ready reference for a GraphQL API: table of contents, every selected type and operation with field-level descriptions and arguments, example queries that run against the schema, and clearly marked deprecations. Use when a GraphQL schema needs an API reference document with operations, types, arguments, example queries, and deprecations laid out for developers to read. Do not use for auditing schema quality, or generating the schema itself. Related topics: coding, graphql."
---

# GraphQL Schema Documenter

A docs-folder-ready reference for a GraphQL API: table of contents, every selected type and operation with field-level descriptions and arguments, example queries that run against the schema, and clearly marked deprecations.

## When to use

Use this skill when a GraphQL schema needs an API reference document with operations, types, arguments, example queries, and deprecations laid out for developers to read. Do not use it for auditing schema quality, or generating the schema itself.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Write the introduction and a table of contents linking every included section.
3. Document each query, mutation, and subscription with its arguments table, return type, errors, and visible auth requirement.
4. Produce a field table per type, enum, interface, and input type, turning SDL descriptions into full sentences and marking missing ones with a TODO.
5. Write one runnable example query per operation with its response shape, when examples are on.
6. Add deprecation callouts when enabled and the pagination and error conventions section for external consumers, then format for the chosen output style.

## Inputs

- **Schema SDL** (longer free text)
- **Sections to include** (choose any: Types, Queries, Mutations, Subscriptions, Enums, Interfaces, Scalars, Input types)
- **Include example queries** (choose one: Yes, No)
- **Output style** (choose one: Plain markdown, GitHub-flavored markdown, HTML)
- **Deprecation notes** (choose one: Include, Omit)
- **Audience** (choose one: Internal frontend team, External API consumers, Both)

## Output

A single document in the chosen format with an introduction, table of contents, Operations section, Types section (one table per type), Examples when enabled, and Deprecations when enabled.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### GraphQL Schema Documenter

Write the API reference for my GraphQL schema, ready to commit to the docs folder.

#### Details
- Schema SDL: {{Schema SDL}}
- Sections to include: {{Sections to include}}
- Include example queries: {{Include example queries}}
- Output style: {{Output style}}
- Deprecation notes: {{Deprecation notes}}
- Audience: {{Audience}}

Open with a short introduction and a table of contents that links to each included section. Document the operations first, since that is where readers start: each query and mutation with its arguments (name, type, required, default, meaning), return type, the errors it can produce, and any auth requirement visible in the schema. Then the types, with a table per type listing field, type, nullability, and the description from the SDL, rewritten into a full sentence where the schema has only a fragment. When examples are on, write one query per operation using real field names from the schema and show the shape of the response. When deprecation notes are on, mark each deprecated field with its reason and the replacement, in a callout the reader cannot miss. For external consumers add a section on pagination and error conventions; for the internal team keep it to the reference. Use only what the schema states and leave a TODO where a description is missing.

## Pitfalls

- Documenting types before operations, so readers scroll past twenty object types to find the one query they need.
- Writing example queries from memory that request fields the schema does not define.
- Inventing descriptions for undocumented fields instead of flagging them, which bakes guesses into the docs.
