GraphQL Schema Refactoring Tool skill for Claude and Codex
A cleaned-up GraphQL schema with a safe migration path: naming brought to one convention, deprecated fields handled the way you chose, comments preserved, 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 schema needs its naming unified, deprecated fields retired or marked, and a version bump with a migration checklist so clients are not broken. Do not use for performance tuning like pagination and complexity limits, or debugging schema load errors. Related topics: coding, graphql.
What it will ask you for
- Existing SDL (longer free text)
- Naming convention (choose one: camelCase, snake_case, PascalCase)
- Deprecation handling (choose one: Keep deprecated fields as they are, Mark fields to retire with @deprecated, Remove fields already marked @deprecated)
- Preserve comments and descriptions (choose one: Yes, No)
- Version bump type (choose one: Patch, Minor, Major)
- Include resolver stubs for changed fields (choose one: Include, Omit)
- Clients that depend on this schema (free text, e.g. "web app and iOS app and partner integrations")
How it works
- Diff the intended changes: every rename, deprecation, removal, merge, or split, each classified as additive, deprecating, or breaking.
- Reconcile the changes with the version bump, converting any forbidden breaking change into a deprecated alias that resolves to the new field.
- Apply the naming convention to fields and arguments, keeping type names PascalCase and carrying descriptions across when preservation is on.
- Write a resolver stub per renamed or added field that delegates the alias to the new resolver, when stubs are enabled.
- Assemble the migration checklist in deployment order: schema, resolvers, each named client, deprecation announcement, removal date.
What you get
A markdown document with the refactored SDL in a graphql block, optional resolver stubs in code blocks, and a migration checklist ordered by deployment step with the version bump stated.
What it watches out for
- Renaming a field in a minor release, which is a breaking change for every client that queries the old name.
- Removing a field marked @deprecated last week before clients have had a release cycle to migrate.
- Dropping descriptions during the rewrite, so the documentation tooling loses everything in one commit.
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.