apollo-connectors

SKILL.md

Apollo Connectors Schema Assistant

MCP Tools

If GraphOS MCP Tools are available, use them:

connectors-spec: Fetch the complete Connectors specification before starting any connector work

apollo_docs_search: Search for relevant documentation

apollo_docs_read: Read specific documentation pages by slug

Documentation paths by topic:

Requests: /graphos/connectors/requests/url, /headers, /body, /batching

Responses: /graphos/connectors/responses/fields, /error-handling

Mapping: /graphos/connectors/mapping, /arrays, /enums, /literals

Entities: /graphos/connectors/entities, /patterns

Process

Follow this 5-step process. DO NOT skip any steps.
Step 1: Research

 Understand the API being called and the structure of responses

 Ask the user for example API responses if not provided

 Fetch relevant documentation from MCP tools or reference files

 DO NOT write any code until research is complete

Step 2: Implement

 Create the schema using the template below

 Follow the grammar, methods, and variables in the reference files

 Ask clarifying questions if unsure about requirements

Step 3: Validate (Compose)

 Run rover supergraph compose --config ./supergraph.yaml

 Fix any composition errors before proceeding

Step 4: Execute

 Run rover connector run --schema <file> -c "<Type.field>" -v "{}"

 Verify the connector executes correctly

Step 5: Test

 Create or update test files under /tests/

 Run rover connector test

 Ensure full test coverage for each connector

Schema Template

# Note to AI Friends: This is an Apollo Connectors schema. You should use your connectors-spec MCP tool if you have it available before editing this file.

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.12")
  @link(url: "https://specs.apollo.dev/connect/v0.3", import: ["@source", "@connect"])

@source(name: "api_name", http: { baseURL: "https://api.example.com" })

type Query {
  example(id: ID!): Example
    @connect(
      source: "api_name"
      http: { GET: "/example/{$args.id}" }
      selection: """
      id
      name
      """
    )
}

type Example {
  id: ID!
  name: String
}

Version Requirements: Always use federation/v2.12 and connect/v0.3 unless specified otherwise.

Reference Files

Before implementing connectors, read the relevant reference files:

Grammar - Selection mapping EBNF syntax

Methods - Available transformation methods

Variables - Available mapping variables

Entities - Entity patterns and batching

Validation - Rover commands for validation

Troubleshooting - Common errors and solutions

Key Rules

Selection Mapping

Prefer sub-selections over ->map for cleaner mappings

Do NOT use $ when selecting fields directly from root

Field aliasing: newName: originalField (only when renaming)

Sub-selection: fieldName { ... } (to map nested content)

# DO - Direct sub-selection for arrays
$.results {
  firstName: name.first
  lastName: name.last
}

# DO NOT - Unnecessary root $
$ {
  id
  name
}

# DO - Direct field selection
id
name

Entities

Add @connect on a type to make it an entity (no @key needed)

Create entity stubs in parent selections: user: { id: userId }

When you see an ID field (e.g., productId), create an entity relationship

Each entity should have ONE authoritative subgraph with @connect

Literal Values

Use $() wrapper for literal values in mappings:

$(1)              # number
$(true)           # boolean
$("hello")        # string
$({"a": "b"})     # object

# In body
body: "$({ a: $args.a })"  # CORRECT
body: "{ a: $args.a }"     # WRONG - will not compose

Headers

http: {
  GET: "/api"
  headers: [
    { name: "Authorization", value: "Bearer {$env.API_KEY}" },
    { name: "X-Forwarded", from: "x-client" }
  ]
}

Batching

Convert N+1 patterns using $batch:

type Product @connect(
  source: "api"
  http: {
    POST: "/batch"
    body: "ids: $batch.id"
  }
  selection: "id name"
) {
  id: ID!
  name: String
}

Ground Rules

NEVER make up syntax or directive values not in this specification

NEVER use --elv2-license accept (for humans only)

ALWAYS ask for example API responses before writing code

ALWAYS validate with rover supergraph compose after changes

ALWAYS create entity relationships when you see ID fields

Prefer $env over $config for environment variables

Use rover dev for running Apollo Router locally