{"id":"d1c0e83d-13a9-46a1-b18c-7fc1b651f5e7","shortId":"T5cwut","kind":"skill","title":"apollo-connectors","tagline":"Guide for integrating REST APIs into GraphQL supergraphs using Apollo Connectors with @source and @connect directives. Use this skill when the user: (1) mentions \"connectors\", \"Apollo Connectors\", or \"REST Connector\", (2) wants to integrate a REST API into GraphQL, (3) references","description":"# Apollo Connectors Schema Assistant\n\n## MCP Tools\n\nIf GraphOS MCP Tools are available, use them:\n- **connectors-spec**: Fetch the complete Connectors specification before starting any connector work\n- **apollo_docs_search**: Search for relevant documentation\n- **apollo_docs_read**: Read specific documentation pages by slug\n\n**Documentation paths by topic:**\n- Requests: `/graphos/connectors/requests/url`, `/headers`, `/body`, `/batching`\n- Responses: `/graphos/connectors/responses/fields`, `/error-handling`\n- Mapping: `/graphos/connectors/mapping`, `/arrays`, `/enums`, `/literals`\n- Entities: `/graphos/connectors/entities`, `/patterns`\n\n## Process\n\nFollow this 5-step process. **DO NOT skip any steps.**\n\n### Step 1: Research\n\n- [ ] Understand the API being called and the structure of responses\n- [ ] Ask the user for example API responses if not provided\n- [ ] Fetch relevant documentation from MCP tools or reference files\n- [ ] DO NOT write any code until research is complete\n\n### Step 2: Implement\n\n- [ ] Create the schema using the template below\n- [ ] Follow the grammar, methods, and variables in the reference files\n- [ ] Ask clarifying questions if unsure about requirements\n\n### Step 3: Validate (Compose)\n\n- [ ] Run `rover supergraph compose --config ./supergraph.yaml`\n- [ ] Fix any composition errors before proceeding\n\n### Step 4: Execute\n\n- [ ] Run `rover connector run --schema <file> -c \"<Type.field>\" -v \"{}\"`\n- [ ] Verify the connector executes correctly\n\n### Step 5: Test\n\n- [ ] Create or update test files under `/tests/`\n- [ ] Run `rover connector test`\n- [ ] Ensure full test coverage for each connector\n\n## Schema Template\n\n```graphql\n# 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.\n\nextend schema\n  @link(url: \"https://specs.apollo.dev/federation/v2.12\")\n  @link(url: \"https://specs.apollo.dev/connect/v0.3\", import: [\"@source\", \"@connect\"])\n\n@source(name: \"api_name\", http: { baseURL: \"https://api.example.com\" })\n\ntype Query {\n  example(id: ID!): Example\n    @connect(\n      source: \"api_name\"\n      http: { GET: \"/example/{$args.id}\" }\n      selection: \"\"\"\n      id\n      name\n      \"\"\"\n    )\n}\n\ntype Example {\n  id: ID!\n  name: String\n}\n```\n\n**Version Requirements:** Always use `federation/v2.12` and `connect/v0.3` unless specified otherwise.\n\n## Reference Files\n\nBefore implementing connectors, read the relevant reference files:\n\n- [Grammar](references/grammar.md) - Selection mapping EBNF syntax\n- [Methods](references/methods.md) - Available transformation methods\n- [Variables](references/variables.md) - Available mapping variables\n- [Entities](references/entities.md) - Entity patterns and batching\n- [Validation](references/validation.md) - Rover commands for validation\n- [Troubleshooting](references/troubleshooting.md) - Common errors and solutions\n\n## Key Rules\n\n### Selection Mapping\n\n- Prefer sub-selections over `->map` for cleaner mappings\n- Do NOT use `$` when selecting fields directly from root\n- Field aliasing: `newName: originalField` (only when renaming)\n- Sub-selection: `fieldName { ... }` (to map nested content)\n\n```\n# DO - Direct sub-selection for arrays\n$.results {\n  firstName: name.first\n  lastName: name.last\n}\n\n# DO NOT - Unnecessary root $\n$ {\n  id\n  name\n}\n\n# DO - Direct field selection\nid\nname\n```\n\n### Entities\n\n- Add `@connect` on a type to make it an entity (no `@key` needed)\n- Create entity stubs in parent selections: `user: { id: userId }`\n- When you see an ID field (e.g., `productId`), create an entity relationship\n- Each entity should have ONE authoritative subgraph with `@connect`\n\n### Literal Values\n\nUse `$()` wrapper for literal values in mappings:\n\n```\n$(1)              # number\n$(true)           # boolean\n$(\"hello\")        # string\n$({\"a\": \"b\"})     # object\n\n# In body\nbody: \"$({ a: $args.a })\"  # CORRECT\nbody: \"{ a: $args.a }\"     # WRONG - will not compose\n```\n\n### Headers\n\n```graphql\nhttp: {\n  GET: \"/api\"\n  headers: [\n    { name: \"Authorization\", value: \"Bearer {$env.API_KEY}\" },\n    { name: \"X-Forwarded\", from: \"x-client\" }\n  ]\n}\n```\n\n### Batching\n\nConvert N+1 patterns using `$batch`:\n\n```graphql\ntype Product @connect(\n  source: \"api\"\n  http: {\n    POST: \"/batch\"\n    body: \"ids: $batch.id\"\n  }\n  selection: \"id name\"\n) {\n  id: ID!\n  name: String\n}\n```\n\n## Ground Rules\n\n- NEVER make up syntax or directive values not in this specification\n- NEVER use `--elv2-license accept` (for humans only)\n- ALWAYS ask for example API responses before writing code\n- ALWAYS validate with `rover supergraph compose` after changes\n- ALWAYS create entity relationships when you see ID fields\n- Prefer `$env` over `$config` for environment variables\n- Use `rover dev` for running Apollo Router locally","tags":["apollo","connectors","skills","apollographql","agent-skills","graphql"],"capabilities":["skill","source-apollographql","skill-apollo-connectors","topic-agent-skills","topic-apollo","topic-graphql"],"categories":["skills"],"synonyms":[],"warnings":[],"endpointUrl":"https://skills.sh/apollographql/skills/apollo-connectors","protocol":"skill","transport":"skills-sh","auth":{"type":"none","details":{"cli":"npx skills add apollographql/skills","source_repo":"https://github.com/apollographql/skills","install_from":"skills.sh"}},"qualityScore":"0.736","qualityRationale":"deterministic score 0.74 from registry signals: · indexed on github topic:agent-skills · official publisher · 71 github stars · SKILL.md body (4,802 chars)","verified":false,"liveness":"unknown","lastLivenessCheck":null,"agentReviews":{"count":0,"score_avg":null,"cost_usd_avg":null,"success_rate":null,"latency_p50_ms":null,"narrative_summary":null,"summary_updated_at":null},"enrichmentModel":"deterministic:skill-github:v1","enrichmentVersion":1,"enrichedAt":"2026-05-18T18:57:01.579Z","embedding":null,"createdAt":"2026-04-18T20:36:00.807Z","updatedAt":"2026-05-18T18:57:01.579Z","lastSeenAt":"2026-05-18T18:57:01.579Z","tsv":"'+1':528 '/api':509 '/arrays':102 '/batch':540 '/batching':96 '/body':95 '/connect/v0.3':281 '/enums':103 '/error-handling':99 '/example':304 '/federation/v2.12':276 '/graphos/connectors/entities':106 '/graphos/connectors/mapping':101 '/graphos/connectors/requests/url':93 '/graphos/connectors/responses/fields':98 '/headers':94 '/literals':104 '/patterns':107 '/supergraph.yaml':196 '/tests':227 '1':26,120,483 '2':34,161 '3':43,188 '4':204 '5':111,219 'accept':569 'add':431 'ai':244 'alias':392 'alway':317,573,582,590 'api':8,40,124,137,287,300,537,577 'api.example.com':291 'apollo':2,13,29,45,72,79,249,611 'apollo-connector':1 'args.a':496,500 'args.id':305 'array':412 'ask':132,180,574 'assist':48 'author':512 'authorit':470 'avail':56,265,343,348 'b':490 'baseurl':290 'batch':356,525,531 'batch.id':543 'bearer':514 'bodi':493,494,498,541 'boolean':486 'c':211 'call':126 'chang':589 'clarifi':181 'cleaner':380 'client':524 'code':155,581 'command':360 'common':365 'complet':64,159 'compos':190,194,504,587 'composit':199 'config':195,602 'connect':18,284,298,432,473,535 'connect/v0.3':321 'connector':3,14,28,30,33,46,60,65,70,208,215,230,238,250,257,329 'connectors-spec':59,256 'content':405 'convert':526 'correct':217,497 'coverag':235 'creat':163,221,444,461,591 'dev':608 'direct':19,388,407,425,558 'doc':73,80 'document':78,84,88,144 'e.g':459 'ebnf':339 'edit':267 'elv2':567 'elv2-license':566 'ensur':232 'entiti':105,351,353,430,440,445,463,466,592 'env':600 'env.api':515 'environ':604 'error':200,366 'exampl':136,294,297,310,576 'execut':205,216 'extend':270 'federation/v2.12':319 'fetch':62,142 'field':387,391,426,458,598 'fieldnam':401 'file':150,179,225,269,326,334 'firstnam':414 'fix':197 'follow':109,170 'forward':520 'friend':245 'full':233 'get':303,508 'grammar':172,335 'grapho':52 'graphql':10,42,241,506,532 'ground':551 'guid':4 'header':505,510 'hello':487 'http':289,302,507,538 'human':571 'id':295,296,307,311,312,422,428,451,457,542,545,547,548,597 'implement':162,328 'import':282 'integr':6,37 'key':369,442,516 'lastnam':416 'licens':568 'link':272,277 'liter':474,479 'local':613 'make':437,554 'map':100,338,349,372,378,381,403,482 'mcp':49,53,146,259 'mention':27 'method':173,341,345 'n':527 'name':286,288,301,308,313,423,429,511,517,546,549 'name.first':415 'name.last':417 'need':443 'nest':404 'never':553,564 'newnam':393 'note':242 'number':484 'object':491 'one':469 'originalfield':394 'otherwis':324 'page':85 'parent':448 'path':89 'pattern':354,529 'post':539 'prefer':373,599 'proceed':202 'process':108,113 'product':534 'productid':460 'provid':141 'queri':293 'question':182 'read':81,82,330 'refer':44,149,178,325,333 'references/entities.md':352 'references/grammar.md':336 'references/methods.md':342 'references/troubleshooting.md':364 'references/validation.md':358 'references/variables.md':347 'relationship':464,593 'relev':77,143,332 'renam':397 'request':92 'requir':186,316 'research':121,157 'respons':97,131,138,578 'rest':7,32,39 'result':413 'root':390,421 'router':612 'rover':192,207,229,359,585,607 'rule':370,552 'run':191,206,209,228,610 'schema':47,165,210,239,251,271 'search':74,75 'see':455,596 'select':306,337,371,376,386,400,410,427,449,544 'skill':22 'skill-apollo-connectors' 'skip':116 'slug':87 'solut':368 'sourc':16,283,285,299,536 'source-apollographql' 'spec':61,258 'specif':66,83,563 'specifi':323 'specs.apollo.dev':275,280 'specs.apollo.dev/connect/v0.3':279 'specs.apollo.dev/federation/v2.12':274 'start':68 'step':112,118,119,160,187,203,218 'string':314,488,550 'structur':129 'stub':446 'sub':375,399,409 'sub-select':374,398,408 'subgraph':471 'supergraph':11,193,586 'syntax':340,556 'templat':168,240 'test':220,224,231,234 'tool':50,54,147,260 'topic':91 'topic-agent-skills' 'topic-apollo' 'topic-graphql' 'transform':344 'troubleshoot':363 'true':485 'type':292,309,435,533 'understand':122 'unless':322 'unnecessari':420 'unsur':184 'updat':223 'url':273,278 'use':12,20,57,166,254,318,384,476,530,565,606 'user':25,134,450 'userid':452 'v':212 'valid':189,357,362,583 'valu':475,480,513,559 'variabl':175,346,350,605 'verifi':213 'version':315 'want':35 'work':71 'wrapper':477 'write':153,580 'wrong':501 'x':519,523 'x-client':522 'x-forward':518","prices":[{"id":"ddd89a18-560e-4692-a9a6-32d961626423","listingId":"d1c0e83d-13a9-46a1-b18c-7fc1b651f5e7","amountUsd":"0","unit":"free","nativeCurrency":null,"nativeAmount":null,"chain":null,"payTo":null,"paymentMethod":"skill-free","isPrimary":true,"details":{"org":"apollographql","category":"skills","install_from":"skills.sh"},"createdAt":"2026-04-18T20:36:00.807Z"}],"sources":[{"listingId":"d1c0e83d-13a9-46a1-b18c-7fc1b651f5e7","source":"github","sourceId":"apollographql/skills/apollo-connectors","sourceUrl":"https://github.com/apollographql/skills/tree/main/skills/apollo-connectors","isPrimary":false,"firstSeenAt":"2026-04-18T22:17:20.886Z","lastSeenAt":"2026-05-18T18:57:01.579Z"},{"listingId":"d1c0e83d-13a9-46a1-b18c-7fc1b651f5e7","source":"skills_sh","sourceId":"apollographql/skills/apollo-connectors","sourceUrl":"https://skills.sh/apollographql/skills/apollo-connectors","isPrimary":true,"firstSeenAt":"2026-04-18T20:36:00.807Z","lastSeenAt":"2026-05-07T22:40:40.210Z"}],"details":{"listingId":"d1c0e83d-13a9-46a1-b18c-7fc1b651f5e7","quickStartSnippet":null,"exampleRequest":null,"exampleResponse":null,"schema":null,"openapiUrl":null,"agentsTxtUrl":null,"citations":[],"useCases":[],"bestFor":[],"notFor":[],"kindDetails":{"org":"apollographql","slug":"apollo-connectors","github":{"repo":"apollographql/skills","stars":71,"topics":["agent-skills","apollo","graphql"],"license":"mit","html_url":"https://github.com/apollographql/skills","pushed_at":"2026-05-14T17:14:05Z","description":"Apollo GraphQL Agent Skills","skill_md_sha":"0535182599120c16266c1efab550ce74b665fe6f","skill_md_path":"skills/apollo-connectors/SKILL.md","default_branch":"main","skill_tree_url":"https://github.com/apollographql/skills/tree/main/skills/apollo-connectors"},"layout":"multi","source":"github","category":"skills","frontmatter":{"name":"apollo-connectors","license":"MIT","description":"Guide for integrating REST APIs into GraphQL supergraphs using Apollo Connectors with @source and @connect directives. Use this skill when the user: (1) mentions \"connectors\", \"Apollo Connectors\", or \"REST Connector\", (2) wants to integrate a REST API into GraphQL, (3) references @source or @connect directives, (4) works with files containing \"# Note to AI Friends: This is an Apollo Connectors schema\".","compatibility":"Requires rover CLI installed. Works with Claude Code and similar AI coding assistants."},"skills_sh_url":"https://skills.sh/apollographql/skills/apollo-connectors"},"updatedAt":"2026-05-18T18:57:01.579Z"}}