---
name: graphql-schema-optimizer
description: "A revised GraphQL schema tuned for runtime cost: query complexity brought under your ceiling, list fields paginated and bounded, cache-friendly field design, N+1 traps called out per field, and a change table so reviewers see exactly what moved. Use when a GraphQL schema allows queries that are too slow or expensive and needs pagination limits, complexity caps, cache-friendly field design, and N+1 fixes without breaking clients. Do not use for fixing schema validation errors, writing documentation, or a naming-only cleanup with a version bump. Related topics: coding, graphql."
---

# GraphQL Schema Optimizer

A revised GraphQL schema tuned for runtime cost: query complexity brought under your ceiling, list fields paginated and bounded, cache-friendly field design, N+1 traps called out per field, and a change table so reviewers see exactly what moved.

## When to use

Use this skill when a GraphQL schema allows queries that are too slow or expensive and needs pagination limits, complexity caps, cache-friendly field design, and N+1 fixes without breaking clients. Do not use it for fixing schema validation errors, writing documentation, or a naming-only cleanup with a version bump.

## 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. Estimate the worst-case query cost from unbounded lists, nesting depth, and fan-out fields, so the changes target what actually exceeds the ceiling.
3. Bound every list with pagination arguments and a maximum page size, and annotate expensive fields with their complexity weight.
4. Separate volatile fields from stable ones and keep entities keyed by stable ids so cache hints can apply, when the focus includes caching.
5. Mark each N+1 field with the batching strategy it needs, and apply naming changes through deprecation aliases rather than hard renames.
6. Write the revised SDL, the per-change table, and the recommendations list, leaving the protected types untouched.

## Inputs

- **Existing SDL** (longer free text)
- **Performance focus** (choose one: Reduce latency, Lower server load, Improve caching, Balance all)
- **Naming convention to enforce** (choose one: camelCase, PascalCase types with camelCase fields, snake_case, Leave as is)
- **Types to leave untouched** (free text, e.g. "Type names that must not change")
- **Complexity ceiling per query** (number from 10 to 10000)
- **Known slow queries** (longer free text)
- **Documentation style** (choose one: Inline comments, Separate markdown, Both)

## Output

A markdown document with the revised SDL in a graphql block, a table of modifications (type, field, change, reason), and a ranked list of performance recommendations.

## Prompt template

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

### GraphQL Schema Optimizer

Revise my GraphQL schema so queries stay cheap, cacheable, and within a complexity budget.

#### Details
- Existing SDL: {{Existing SDL}}
- Performance focus: {{Performance focus}}
- Naming convention to enforce: {{Naming convention to enforce}}
- Types to leave untouched: {{Types to leave untouched}}
- Complexity ceiling per query: {{Complexity ceiling per query}}
- Known slow queries: {{Known slow queries}}
- Documentation style: {{Documentation style}}

Estimate the cost of the worst-case query first: unbounded lists, deep nesting, and fields that fan out to other services multiply. Bound every list with pagination arguments and a maximum page size, add a complexity annotation or comment per expensive field, and cap nesting where the ceiling would otherwise be exceeded. For caching, keep entity types keyed by a stable id, separate volatile fields (counts, prices, presence) from stable ones so a cache hint can cover the stable part, and avoid arguments on fields that make responses unique per caller when the focus is caching. Mark each field that will trigger N+1 resolution with the batching strategy it needs. Apply the naming convention with a deprecation alias for each rename rather than a hard break. Skip the protected types entirely. Produce the revised SDL, a table with one row per modification (type, field, change, reason), and a prioritised list of performance recommendations beyond the schema, such as persisted queries or response caching, in the documentation style chosen.

## Pitfalls

- Renaming fields outright for consistency, which is a breaking change that no performance gain justifies.
- Setting a complexity ceiling without weighting list fields by page size, so a request for 1000 items costs the same as one.
- Marking whole types as cacheable when one field on them changes every second, which serves stale data everywhere.
