Version-aware guide for configuring and running Apollo Router for federated GraphQL supergraphs. Generates correct YAML for both Router v1.x and v2.x. Use this skill when: (1) setting up Apollo Router to run a supergraph, (2) configuring routing, headers, or CORS, (3)
Installs just this skill. Get the whole plugin for auto-invocation.
⚡ How it fires
How this skill gets triggered: by you, by Claude, or both.
Fires itselfClaude auto-loads it when your prompt matches the work.
You can call itInvoke it directly when you want it.
Slash command/apollo-router
👁️ Context preview
The summary Claude sees to decide when to auto-load this skill.
Version-aware guide for configuring and running Apollo Router for federated GraphQL supergraphs. Generates correct YAML for both Router v1.x and v2.x. Use this skill when: (1) setting up Apollo Router to run a supergraph, (2) configuring routing, headers, or CORS, (3)
📊 Stats
Stars98
Forks11
LanguageShell
LicenseMIT
📦 Ships with apollo-skills
</> SKILL.md
apollo-router.SKILL.md
---name: apollo-router
description: >
Version-aware guide for configuring and running Apollo Router for federated GraphQL supergraphs.
Generates correct YAML for both Router v1.x and v2.x. Use this skill when:
(1) setting up Apollo Router to run a supergraph,
(2) configuring routing, headers, or CORS,
(3) implementing custom plugins (Rhai scripts or coprocessors),
(4) configuring telemetry (tracing, metrics, logging),
(5) troubleshooting Router performance or connectivity issues.
license: MIT
compatibility: Linux/macOS/Windows. Requires a composed supergraph schema from Rover or GraphOS.
metadata:
author: apollographql
version: "2.4.0"
allowed-tools: Bash(router:*) Bash(./router:*) Bash(rover:*) Bash(curl:*) Bash(docker:*) Read Write Edit Glob Grep
---# Apollo Router Config Generator
Apollo Router is a high-performance graph router written in Rust for running Apollo Federation 2 supergraphs. It sits in front of your subgraphs and handles query planning, execution, and response composition.
**This skill generates version-correct configuration.** Router v1 and v2 have incompatible config schemas in several critical sections (CORS, JWT auth, connectors). Always determine the target version before generating any config.
## Step 1: Version Selection
- [ ] Connectors (REST API integration — Router v2 only; GA key is `connectors`, early v2 preview key was `preview_connectors`)
- [ ] Subscriptions
- [ ] Header Propagation
- [ ] Response Caching (entity + root field caching with Redis — Router v2 only, v2.6.0+)
## Step 4: Gather Parameters
For each selected feature, collect required values.
- Use section templates from `templates/{version}/sections/` for `auth`, `cors`, `headers`, `limits`, `telemetry`, and `traffic-shaping`.
- For Connectors in v2, use `templates/v2/sections/connectors.yaml` as the source.
- For APQ and subscriptions, copy the snippet from the selected base template (`templates/{version}/production.yaml` or `templates/{version}/development.yaml`) or from references.
- Only offer Connectors when `ROUTER_VERSION=v2`.
### CORS
- List of allowed origins (never use `"*"` for production)
> **Security: data leakage risk.** Before generating any response cache config, you MUST ask the user which types and fields return user-specific data. Cached data defaults to shared — subgraph responses without `Cache-Control: private` are visible to all users. User-specific subgraphs must return `Cache-Control: private` and have `private_id` configured on the router.
- Ask: **How do you identify users?** (JWT `sub` claim, session token, API key)
- Redis URL (default: `redis://localhost:6379`)
- Default TTL (default: `5m`)
- Enable active invalidation? If yes: invalidation listen address and shared key
- Use section template: `templates/v2/sections/response-caching.yaml`
- For security requirements, schema directives, and advanced config: `references/response-caching.md` (start with the Security section)
## Step 5: Generate Config
1. Load the correct version template from `templates/{version}/`
2. Assemble section templates for supported sectioned features, then merge base-template snippets for APQ/subscriptions as needed
3. Inject user-provided parameters
4. Add a comment block at the top stating the target version
## Step 6: Validate
Run the [post-generation checklist](validation/checklist.md):
- [ ] All env vars referenced in config are documented
- [ ] CORS origins don't include wildcards (production)
- [ ] Rate limiting is on `router:` (client-facing), not only `all:` (subgraph)
- [ ] JWT uses `issuers` (v2) not `issuer` (v1), or vice versa
- [ ] If production: introspection=false, sandbox=false, subgraph_errors=false
- [ ] Health check is enabled
- [ ] Homepage is disabled (production)
- [ ] Run: `router config validate <file>` if Router binary is available
## Required Validation Gate (always run)
After generating or editing any `router.yaml`, you MUST:
1. Run `validation/checklist.md` and report pass/fail for each checklist item.
2. Run `router config validate <path-to-router.yaml>` if Router CLI is available.
3. If Router CLI is unavailable, state that explicitly and still complete the checklist.
4. Do not present the configuration as final until validation is completed.
## Step 7: Conditional Next Steps Handoff
After answering any Apollo Router request (config generation, edits, validation, or general Router guidance), decide whether the user already has runnable prerequisites:
- GraphOS-managed path: `APOLLO_KEY` + `APOLLO_GRAPH_REF`, or
- Local path: a composed `supergraph.graphql` plus reachable subgraphs
If prerequisites are already present, do not add extra handoff text.
If prerequisites are missing or unknown, end with a concise **Next steps** handoff (1-3 lines max) that is skill-first and command-free:
1. Suggest the `rover` skill to compose or fetch the supergraph schema.
2. Suggest continuing with `apollo-router` once the supergraph is ready to validate and run with the generated config.
3. If subgraphs are missing, suggest `apollo-server`, `graphql-schema`, and `graphql-operations` skills to scaffold and test.
Do not include raw shell commands in this handoff unless the user explicitly asks for commands.
## Quick Start (skill-first)
1. Use this `apollo-router` skill to generate or refine `router.yaml` for your environment.
2. Choose a runtime path:
- GraphOS-managed path: provide `APOLLO_KEY` and `APOLLO_GRAPH_REF` (no local supergraph composition required).
- Local supergraph path: use `graphql-schema` + `apollo-server` to define/run subgraphs, then use `graphql-operations` for smoke tests, then use the `rover` skill to compose or fetch `supergraph.graphql`.
3. Use this `apollo-router` skill to validate readiness (`validation/checklist.md`) and walk through runtime startup inputs.
Default endpoint remains `http://localhost:4000` when using standard Router listen defaults.
If the user asks for executable shell commands, provide them on request. Otherwise keep Quick Start guidance skill-oriented.
-s, --supergraph <PATH> Path to supergraph schema file
-c, --config <PATH> Path to router.yaml configuration
--dev Enable development mode
--hot-reload Watch for schema changes
--log <LEVEL> Log level (default: info)
--listen <ADDRESS> Override listen address
-V, --version Print version
-h, --help Print help
```
## Ground Rules
- ALWAYS determine the target Router version (v1 or v2) before generating config
- DEFAULT to v2 for new projects
- ALWAYS include a comment block at top of generated config stating the target version
- ALWAYS use `--dev` mode for local development (enables introspection and sandbox)
- ALWAYS disable introspection, sandbox, and homepage in production
- PREFER GraphOS managed mode for production (automatic updates, metrics)
- USE `--hot-reload` for local development with file-based schemas
- NEVER expose `APOLLO_KEY` in logs or version control
- USE environment variables (`${env.VAR}`) for all secrets and sensitive config
- PREFER YAML configuration over command-line arguments for complex setups
- TEST configuration changes locally before deploying to production
- WARN if user enables `allow_any_origin` or wildcard CORS in production
- RECOMMEND `router config upgrade router.yaml` for v1 → v2 migration instead of regenerating from scratch
- MUST run `validation/checklist.md` after every router config generation or edit
- MUST run `router config validate <file>` when Router CLI is available
- MUST report when CLI validation could not run (for example, Router binary missing)
- MUST append a brief conditional handoff when runtime prerequisites are missing or unknown
- MUST make this handoff skill-first and avoid raw shell commands unless the user explicitly requests commands
- MUST keep Quick Start guidance skill-first and command-free unless the user explicitly requests commands
- MUST state that Rover is required only for the local supergraph path; GraphOS-managed runtime does not require local Rover composition
- USE `max_depth: 50` as the default starting point, not 15 (too aggressive) or 100 (too permissive)
- RECOMMEND `warn_only: true` for initial limits rollout to observe real traffic before enforcing
- ONLY offer Response Caching when `ROUTER_VERSION=v2` (requires v2.6.0+)
- ALWAYS use `${env.*}` for Redis URLs, passwords, and invalidation shared keys
- NEVER enable `response_cache.debug: true` in production config
- RECOMMEND combining Cache-Control headers (passive TTL) with @cacheTag (active invalidation) for production
- ALWAYS ask which fields return user-specific data before generating response cache config — never assume all data is safe to cache as shared
- ALWAYS configure `private_id` for subgraphs that serve user-specific data, and ensure those subgraphs return `Cache-Control: private` (via `@cacheControl(scope: PRIVATE)` in Apollo Server, or by setting the header directly in other frameworks)
- NEVER generate response cache config without addressing private data — if the user says "no user-specific data", confirm explicitly before proceeding
- ALWAYS bind the invalidation endpoint to `127.0.0.1`, NEVER `0.0.0.0` in production
