Apollo Schema Proposal Reviewer

An AI agent skill that reviews Apollo GraphQL schema proposals against Federation best practices. It fetches proposal data from Apollo Studio, performs deterministic schema diffing, gathers official Apollo documentation and your organization's custom best practices, then delivers structured review feedback with severity levels, actionable suggestions, and linked references.

How It Works

1. Fetches proposal data from Apollo Studio via GraphQL API
2. Diffs schemas deterministically — compares the source (pre-proposal) and backing (proposed) subgraph schemas to produce a structured changeset
3. Gathers best practices — pulls official Apollo Federation docs via the GraphOS MCP server and reads any custom .md best practices you maintain locally
4. Generates a structured review — the AI evaluates every change against best practices and produces feedback organized by subgraph and change, with severity levels (ERROR, WARNING, INFO, SUGGESTION)
5. Posts the review (optional) — writes the review as a comment directly on the Apollo Studio proposal

Prerequisites

• Node.js v18+
• An Apollo Studio API key with read access to your graph's proposals (and write access if you want to post review comments)
• An AI agent that supports the standard skill format (SKILL.md with frontmatter, ${SKILL_DIR}, and $ARGUMENTS)
• Apollo GraphOS MCP server enabled in Cursor (used to fetch official Apollo documentation)

Installation

1. Clone or copy the skill into your machine

git clone <repo-url> /path/to/schema-reviewer-skill

Or copy the directory anywhere on your local filesystem.

2. Register the skill in Cursor

Add the skill to your Cursor configuration so the agent can discover it. Create or edit ~/.claude/skills/schema-reviewer/SKILL.md to point to this directory, or configure the skill path in your Cursor settings so that the SKILL.md at the root of this project is picked up.

The SKILL.md file is the entry point — it contains the full orchestration instructions the agent follows.

3. Install script dependencies

cd /path/to/schema-reviewer-skill/scripts
npm install

This installs the graphql package (v16.9+) used for deterministic schema parsing and normalization.

4. Configure the skill

Copy the example config and fill in your values:

cp config.example.json config.json

Edit config.json:

{
  "apollo_api_key": "your-apollo-api-key-here",
  "custom_docs_path": "/path/to/your/custom-schema-docs",
  "custom_docs_base_url": "https://github.com/your-org/your-repo/tree/main/custom-schema-docs",
  "auto_post_comment": false
}

Field	Required	Description
apollo_api_key	Yes	Your Apollo Studio API key for authenticating GraphQL requests
custom_docs_path	No	Absolute path to a local directory of .md files containing your organization's schema best practices. Leave as "" if not used.
custom_docs_base_url	No	URL prefix for generating clickable links to your custom docs in the review output (e.g., a GitHub tree URL). Leave as "" if not used.
auto_post_comment	No	When true, the review is automatically posted as a comment on the Apollo proposal without asking for confirmation. Defaults to false.

Note: config.json is git-ignored. If you skip this step, the agent will walk you through setup interactively on first run.

5. Enable the Apollo GraphOS MCP server

The skill fetches official Apollo Federation documentation via the GraphOS MCP server. Make sure it is enabled in your Cursor MCP settings. The agent uses the ApolloDocsRead tool to pull documentation pages by slug.

Usage

In Cursor's agent mode, invoke the skill by asking it to review a proposal. You can provide the proposal in several formats:

Full Apollo Studio URL (recommended):

Review proposal https://studio.apollographql.com/graph/my-graph/proposal/p-100

Human-readable ID with graph name:

Review proposal p-100 on the my-graph graph

Internal UUID:

Review proposal abc12345-def6-7890-ghij-klmnopqrstuv

The agent will handle the rest — fetching data, diffing schemas, gathering docs, producing the review, and optionally posting it.

Project Structure

schema-reviewer-skill/
├── SKILL.md                        # Agent skill entry point (orchestration instructions)
├── config.example.json             # Example configuration
├── config.json                     # Your local configuration (git-ignored)
├── references/
│   └── review-prompt.md            # Review criteria, severity levels, and output format
└── scripts/
    ├── package.json                # Script dependencies (graphql)
    ├── fetch-proposal.mjs          # Fetches proposal data from Apollo Studio API
    ├── schema-diff.mjs             # Deterministic schema diff engine
    └── post-comment.mjs            # Posts review comment back to Apollo Studio

Scripts

Script	Purpose
fetch-proposal.mjs	Calls the Apollo Studio GraphQL API to retrieve full proposal data including source/backing variant schemas, revision history, and check workflow status. Supports URL, human-readable ID, and UUID input formats.
schema-diff.mjs	Parses and normalizes GraphQL schemas, then produces a structured diff grouped by subgraph. Detects added/removed/modified types, fields, directives, enum values, union members, and input fields.
post-comment.mjs	Posts a markdown comment to a specific proposal revision in Apollo Studio via the AddCommentToProposal mutation.

Custom Best Practices

You can maintain a directory of .md files with your organization's schema conventions. When custom_docs_path is configured, the agent reads all markdown files in that directory and incorporates them into the review.

Custom best practices take precedence over Apollo's official documentation when there is a conflict. This lets you enforce organization-specific conventions (e.g., naming patterns, required directives, domain-specific rules) while still getting coverage from Apollo's general guidance.

Set custom_docs_base_url to the browsable URL prefix for these files (e.g., a GitHub tree URL) so the review output includes clickable links to your docs.

Review Output

The review is formatted as structured markdown with:

• A summary of overall proposal quality
• Findings grouped by subgraph, then by individual change
• Four severity levels: ERROR (breaks federation), WARNING (problematic patterns), INFO (best practice guidance), SUGGESTION (optimizations)
• Every finding includes the affected path, explanation, fix suggestion, best practice source attribution, and a documentation link