---
name: graphql-schema-analyzer
description: "An audit of an existing GraphQL schema: an inventory of types and operations, the gaps a client team will hit (missing descriptions, nullable-everything fields, unpaginated lists, deprecated fields still in use), and prioritised recommendations. Use when an existing GraphQL schema needs an audit for client-facing gaps like missing descriptions, unpaginated lists, loose nullability, and stale deprecations before more clients build on it. Do not use for designing a schema from scratch, fixing a schema that fails to load, or writing end-user docs. Related topics: coding, graphql."
---

# GraphQL Schema Analyzer

An audit of an existing GraphQL schema: an inventory of types and operations, the gaps a client team will hit (missing descriptions, nullable-everything fields, unpaginated lists, deprecated fields still in use), and prioritised recommendations.

## When to use

Use this skill when an existing GraphQL schema needs an audit for client-facing gaps like missing descriptions, unpaginated lists, loose nullability, and stale deprecations before more clients build on it. Do not use it for designing a schema from scratch, fixing a schema that fails to load, or writing end-user docs.

## 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. Inventory the schema: counts per kind, the root operations, and the entry points clients will use most.
3. Assess each selected focus area and record every finding with the type and field it concerns.
4. List each @deprecated field with its reason and replacement status when deprecations are on.
5. Weight the findings by the consumer type so a public API's breaking risks rank above an internal service's cosmetic ones.
6. Write the recommendations ranked by impact and cost, marking which are breaking changes, sized to the chosen depth.

## Inputs

- **Schema SDL** (longer free text)
- **Focus areas** (choose any: Types, Queries, Mutations, Subscriptions, Directives, Scalars, Pagination, Nullability)
- **Depth of analysis** (choose one: Overview, Detailed, Exhaustive)
- **Highlight deprecated fields** (choose one: Yes, No)
- **Who consumes it** (choose one: One web client, Web and mobile clients, Public API with external developers, Internal services)
- **Output format** (choose one: Markdown report, JSON summary, HTML page)

## Output

A report in the chosen format with sections Summary, Inventory, Findings (grouped by focus area with type and field references), Deprecations when requested, and Recommendations ranked with a breaking flag.

## Prompt template

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

### GraphQL Schema Analyzer

Audit my GraphQL schema and tell me where it will hurt clients and maintainers.

#### Details
- Schema SDL: {{Schema SDL}}
- Focus areas: {{Focus areas}}
- Depth of analysis: {{Depth of analysis}}
- Highlight deprecated fields: {{Highlight deprecated fields}}
- Who consumes it: {{Who consumes it}}
- Output format: {{Output format}}

Inventory first: count types, inputs, enums, interfaces, unions, and the root operations, and list the entry points a client would reach for. Then assess against the focus areas: fields that lack descriptions, lists returned without pagination arguments, fields nullable by default where the data is always present (and non-null fields that can actually fail), mutations that return a bare type instead of a payload with errors, input types reused across unrelated mutations, custom scalars without a documented format, and naming that drifts between camelCase and snake_case. When deprecations are on, list each @deprecated field with its reason and whether a replacement exists. Weight findings by consumer: a public API treats every breaking risk as high, an internal service tolerates more. Rank recommendations by impact and the cost to change, and note which ones are breaking. Match the length to the depth selected: an overview is one page.

## Pitfalls

- Flagging every nullable field as a problem when GraphQL nullability is meant to express partial failure, not optional data.
- Reporting counts and structure without saying what a client would do differently, which reads as a listing rather than an audit.
- Recommending breaking renames to a public schema without an accompanying deprecation path.
