apollo-federation – GraphQL 联邦架构开发 Skill

Skill 详细介绍

apollographql/skills#apollo-federation 是 Apollo GraphQL 官方 skills 仓库中的一个 Agent Skill，名称可以识别为 apollo-federation。它面向的是 Apollo Federation（联邦图）相关的开发与运维工作，帮助 AI Agent 在涉及联邦架构、子图设计、supergraph 组合、schema 协作等任务时给出更符合 Apollo 官方实践的方案。

它本身不是一个可以独立运行的软件，也不是一个 npm 包、CLI 工具或服务端组件。它本质上属于“指令集 / 知识型 Skill”：通过一段结构化的 SKILL.md 指令，把 Apollo Federation 的概念体系、推荐工作流和常见约束注入到 Agent 的上下文中，让 Agent 在处理联邦图相关任务时，表现出接近熟悉 Apollo Federation 的开发者的判断力。

核心用途

• 设计或审查 Federation 子图（subgraph）schema
• 规划 supergraph 组合方式与路由（router / gateway）配置思路
• 解释 Apollo Federation 概念：实体（entity）、key、reference resolver、shareable、override、inaccessible 等指令
• 协助判断某个字段或类型应该放在哪个子图
• 迁移单体 GraphQL schema 到联邦架构时的拆分建议
• 排查子图之间字段冲突、类型不一致、组合失败等典型问题

它主要解决什么问题

Apollo Federation 的规则比较细，版本差异也大（Federation 1 与 Federation 2 的指令语义差别明显）。很多开发者知道概念，但在具体写 schema、决定字段归属、处理组合冲突时容易踩坑。这个 Skill 的作用，是把这些规则和最佳实践以“随叫随到的上下文”形式提供给 Agent，减少来回查文档和试错。

它不是什么

• 不是 Apollo Router 或 Apollo Gateway 本身
• 不是 rover CLI 的替代品
• 不会替用户自动部署或托管 supergraph
• 不提供 Apollo Studio / GraphOS 账号或云端能力
• 不保证生成的 schema 一定能通过组合，最终仍需本地 rover 或 GraphOS 校验

典型任务与使用场景

1. 新项目规划联邦架构，需要决定子图边界
2. 把已有单体 GraphQL 服务拆成多个子图
3. 审查一段 Federation schema 是否符合当前 Federation 版本规范
4. 解释某个指令（如 @key、@shareable、@override）在当前场景下是否该用
5. 排查 “composition error” 类问题的可能原因
6. 编写或校对子图的 reference resolver 逻辑思路

适合哪些用户

• 正在使用或准备使用 Apollo Federation 的后端 / 平台工程师
• 负责 GraphQL 网关或 API 聚合层的开发者
• 需要维护多个 GraphQL 服务、想统一 schema 协作方式的团队

不太适合的需求

• 只想写一个独立的单图（monolithic）GraphQL 服务，不涉及联邦
• 使用的是非 Apollo 的 schema 联合方案（例如 GraphQL Mesh、Hasura 等），语义不同
• 需要直接运行、部署或托管服务，而不只是获取设计与判断建议

与普通 Agent 自身能力的区别

通用 Agent 对 Apollo Federation 的知识通常停留在概念层面，容易混淆 Federation 1 和 Federation 2 的指令规则，也容易给出“看起来合理但不合规”的 schema。加载该 Skill 后，Agent 在联邦相关的指令用法、字段归属、组合约束等问题上，会更倾向于遵循 Apollo 官方推荐路径，而不是自由发挥。

Skill 安全评估

总体判断：来自 Apollo GraphQL 官方组织的 Skill，来源可信度较高。从这类 Skill 的行为模式看，它主要是提供指令和知识上下文，本身并不需要常驻进程、系统级权限或网络监听，风险面相对有限。但具体行为仍取决于 Agent 运行时授予它的权限。

来源可信度

• Skill 位于 apollographql/skills 仓库，组织方为 Apollo GraphQL，属于该技术领域的官方一方来源
• 官方组织的 Skill 仓库通常比第三方个人发布的 Skill 更可审查，但仍建议在使用前查看仓库的 License、最近提交记录和 issue 情况

文件与 Shell 权限

• 如果 Agent 只把它当作知识型 Skill 加载，通常只需要读取自身 SKILL.md 内容，不需要额外文件读写或 Shell 权限
• 如果用户在该 Skill 生效期间让 Agent 修改项目里的 schema 文件或运行命令，那么实际风险来自 Agent 的通用工具权限，而不是这个 Skill 本身
• 建议：若只需要它做 schema 审查、方案讨论和解释，可以不授予 Agent 自动执行 Shell 的权限，由用户手动运行 rover 等命令进行校验

网络与凭证

• 该 Skill 本身不应要求 API Key、Token 或 OAuth 凭证
• 如果后续任务涉及 Apollo GraphOS / Apollo Studio（例如 graph ref、API key），那是用户项目层面的凭证需求，与 Skill 本身无关；这类凭证不要在对话里随意粘贴，应通过 Agent 官方的密钥管理机制传入

Prompt Injection 与供应链风险

• 作为官方仓库中的 Skill，其 SKILL.md 内容由维护者控制，被注入恶意指令的概率较低，但仍建议在首次使用前通读一遍 SKILL.md，确认没有意外指令
• Skill 若引用了外部文档或远程资源，需注意 Agent 是否会自动抓取这些内容；如有，需确认抓取目标可信
• 不要把未审查的第三方 fork 或镜像版本当作官方版本使用

可落地的降风险建议

1. 只从 apollographql/skills 官方仓库获取该 Skill，避免使用来源不明的同名副本
2. 首次使用前通读 SKILL.md，确认指令范围符合预期
3. 若仅用于咨询和审查，可关闭 Agent 自动执行 Shell 的权限
4. 不要在对话中粘贴真实的 GraphOS API Key 或生产环境凭证
5. 对 Skill 输出的 schema 修改建议，落地前用 rover 等官方工具校验一次

Skill 使用要求

一、Agent / 客户端

该 Skill 来自 Apollo GraphQL 官方 skills 仓库，属于 Agent Skill 形态。官方主要面向支持 Skills 或自定义指令加载机制的 Agent 环境。具体以官方仓库当前说明为准。

• Claude Code：这类 Agent Skill 与 Claude Code 的 Skill 加载机制较为契合，可优先在 Claude Code 中尝试使用
• Codex、Cursor、Trae、OpenClaw、WorkBuddy：官方没有公布完整的第三方 Agent 兼容列表。从 Agent Skill 的工作方式看，在支持 Skills、自定义 Skill 或类似指令加载机制的环境中，通常也可以尝试使用；不同 Agent 的加载方式和兼容程度可能不同，具体以对应 Agent 当前版本为准

二、运行环境 / 依赖

该 Skill 本身是知识型指令，通常不需要额外的运行时依赖即可加载。但后续用它处理的任务可能引入一些工具依赖。

官方没有明确说明该 Skill 对 Node.js、Python 或操作系统的具体版本要求，不要自行假定。具体以官方仓库当前说明为准。

三、权限

• 文件读取：可选。若让 Agent 读取项目中的 schema 文件进行审查，则需要
• 文件写入：可选。若让 Agent 直接修改 schema 文件，则需要；仅咨询时不需要
• Shell：可选。用于运行 rover 等校验命令；仅咨询时不需要，可关闭
• 网络：可选。用于查官方文档或访问 GraphOS；仅本地讨论时不需要
• Docker / GitHub：非该 Skill 必需

四、账号 / API Key

• Skill 本身：不需要账号、API Key 或 Token
• Skill 后续涉及的 Apollo GraphOS / Apollo Studio 任务：可能需要在用户项目侧配置 graph ref 和 API key，这属于项目需求，不是 Skill 安装要求

最小使用条件

1. 一个支持 Skill 加载机制的 Agent 环境
2. 能读取该 Skill 的 SKILL.md
3. （可选）项目中的 Federation schema 文件，用于具体审查任务
4. （可选）rover CLI，用于落地前的组合校验

Skill 安装、使用与卸载教程

一、安装

可以直接复制本页面提供的 Skill 安装指令，粘贴到对应 Agent 或终端中执行。LemonAIKit 的 Skill 详情页已经单独给出了安装指令，这里不再重复完整命令。

如果用户不确定自己的 Agent 如何安装该 Skill，可以直接询问当前 Agent：

如何安装 apollographql/skills#apollo-federation？

如何在 Claude Code 中安装 apollographql/skills#apollo-federation？

如何在 Codex 中安装 apollographql/skills#apollo-federation？

如何在 Cursor 中安装 apollographql/skills#apollo-federation？

让当前 Agent 根据自己的 Skill 加载 / 管理机制给出对应步骤，通常比手动猜测安装路径更稳妥。

目前官方资料未明确说明该 Skill 是否存在特殊的额外安装条件。若官方仓库有额外说明，以仓库当前内容为准。

二、安装后如何使用

安装后，通常不需要专门的命令触发。当对话内容涉及 Apollo Federation、子图、supergraph、联邦 schema、组合错误等主题时，Agent 会自然调用该 Skill 的上下文来组织回答。也可以在提问时显式点名这个 Skill。

适合交给它的任务类型：

• 设计或审查子图 schema
• 判断字段、类型在联邦架构中的归属
• 解释 Federation 指令用法
• 排查组合相关问题
• 规划从单体到联邦的迁移路径

自然语言使用示例：

使用 apollo-federation，帮我审查这段子图 schema 是否符合 Federation 2 的规范。

使用 apollo-federation，说明 @shareable 和 @override 在什么场景下应该使用。

使用 apollo-federation，帮我把这个单体 GraphQL schema 拆分成多个子图的初步方案。

三、卸载

卸载方式取决于用户使用的 Agent 及其 Skill 管理机制，不同 Agent 的安装位置和管理方式可能不同，并不存在一个统一的卸载命令。

推荐做法：

1. 使用对应 Agent 或 Skill 管理器提供的删除 / 移除方式，删除 apollographql/skills#apollo-federation 对应的 Skill
2. 如果不确定具体操作，直接询问当前 Agent：

如何卸载 apollographql/skills#apollo-federation？

让 Agent 根据自己的 Skill 加载机制给出移除步骤，通常比手动查找目录更稳妥。官方资料未明确提供统一的卸载命令，不要自行编造。

常见问题

1. 可以同时安装到多个 Agent 中吗？

通常可以。Skill 文件本身是独立内容，不同 Agent 各自维护自己的 Skill 存储位置。分别在各 Agent 中安装即可，互不影响。需要注意各 Agent 可能对 Skill 目录结构有不同约定。

2. 安装后 Agent 没有识别到这个 Skill，怎么办？

先确认 SKILL.md 是否放在该 Agent 期望的位置，以及 Agent 是否已重新加载 Skill 列表。不同 Agent 对 Skill 目录、命名和重启要求不同，直接问当前 Agent“为什么没有加载 apollographql/skills#apollo-federation”通常更快。

3. Skill 更新后需要重新安装吗？

取决于安装方式。如果是从仓库拉取并本地保存，需要重新同步最新版本；如果 Agent 采用引用方式加载，可能自动生效。以对应 Agent 的 Skill 管理机制为准。

4. 这个 Skill 会修改我现有的项目文件吗？

Skill 本身只是提供指令上下文，不会主动修改文件。实际是否会改动项目，取决于用户是否让 Agent 执行编辑或命令操作。仅做咨询时，可以只授予只读权限。

5. 使用它可以关闭 Shell 权限吗？

可以。如果只是用该 Skill 做 schema 讨论、指令解释和方案审查，完全可以关闭 Agent 的自动 Shell 执行。需要校验 schema 时，由用户手动运行 rover 等命令即可。

6. 这个 Skill 适合生产环境直接使用吗？

它输出的是设计和审查建议，最终 schema 是否可上线，仍应以官方工具（如 rover）的组合校验结果和团队评审为准。不要仅凭 Skill 输出就跳过校验。

7. 中国大陆使用是否有网络要求？

Skill 本身的加载和使用通常不需要特殊网络。如果让 Agent 联网查 Apollo 官方文档或访问 GraphOS 相关服务，可能对网络连通性有要求。具体以用户实际环境和 Agent 联网策略为准。