GraphQL Schema Debugger skill for Claude and Codex
A fix for a GraphQL schema that refuses to load or misbehaves: each validation error or linter warning traced to its line, why the server rejects it, the…
Install it once and Claude or Codex runs it for you. When your request matches, your AI loads the skill, asks for anything it is missing, and works through the template itself. Prefer to fill it in by hand? See the full prompt template.
Download the skill (.zip) · View SKILL.md
When it is used
Use when a GraphQL server rejects its schema, a linter reports errors, or a field returns null or triggers N+1 queries and the user has the SDL and the error output. Do not use for a general schema quality audit with no failing error, or designing a new schema. Related topics: coding, graphql.
What it will ask you for
- Schema SDL (longer free text)
- Error output (longer free text)
- Database (choose one: PostgreSQL, MongoDB, MySQL, Elasticsearch, Other)
- Resolver language (choose one: Node.js, Python, Java, Go, Other)
- Specific concern (choose any: Circular refs, N+1 queries, Type mismatches, Naming, Missing descriptions, Schema will not load, Field returns null unexpectedly)
How it works
- Map each error message to the SDL line it refers to, distinguishing the use site from the definition that actually needs the change.
- Explain for each issue what the spec or server rejects and give the corrected snippet for only that part of the schema.
- Classify each issue as schema-side or resolver-side, and write the resolver fix in the selected language for null fields and N+1 patterns, batching against the named database.
- Work through the specific concerns in the order given so the user's priority is addressed first.
- List two or three practices that would catch these errors earlier in development.
What you get
A markdown report with a numbered issue list (line reference, why it fails, corrected snippet), a Resolver fixes section with code where relevant, and a short Prevention list.
What it watches out for
- Editing the type where the error is reported when the real defect is in the type it references, which moves the error rather than fixing it.
- Adding a nullable marker to make a validation error disappear instead of resolving the input-type cycle behind it.
- Treating a null field as a schema bug when the resolver simply never returns the key the field expects.
How to install
Claude.ai and the Claude desktop app
- Download the skill .zip.
- Open Settings, then Capabilities, and find Skills.
- Choose Upload skill and select the .zip.
- Ask Claude for help with the task. It loads the skill when your request matches.
Claude Code
- Download the skill .zip.
- Unzip it into ~/.claude/skills/ (or .claude/skills/ inside a project).
- Start a new session. Claude Code loads the skill when your request matches.
Codex
- Download the skill .zip.
- Unzip it into ~/.agents/skills/ (or .agents/skills/ inside a project).
- Codex picks it up on its own. Type $ and the skill name to use it, or just ask for the task.
Cursor
- Download the Cursor rule (.mdc).
- Save it in .cursor/rules/ inside your project.
- Cursor's agent applies the rule when your request matches its description.
AGENTS.md (Codex, Cursor, and other coding agents)
- Copy the AGENTS.md section.
- Paste it into AGENTS.md at the root of your repository, creating the file if needed.
- Coding agents that read AGENTS.md follow it when your request fits.