Claude Media
Claude Codeのapollo-skillsプラグインでFederationとRouterを扱う
Claude CodeClaude連携チュートリアル

Claude Codeのapollo-skillsプラグインでFederationとRouterを扱う

apollo-skillsプラグインは、Federation・Router・Rover・GraphQLスキーマ設計のスキルをClaude Codeに足します。導入手順、スキルの呼び分け、LSPとMCPの同梱内容を説明します。

読了目安 約16分

apollo-skillsは、Apollo GraphQLが配布しているClaude Codeプラグインです。Apollo Federationのサブグラフ設計、Apollo Routerの設定、Rover CLIの操作、GraphQLスキーマの設計指針を、スキルとしてClaude Codeに足します。

Federationのディレクティブやrouter.yamlのバージョン差は、モデルの記憶だけに頼ると外しやすい領域です。このプラグインは、その手順と注意点をスキルに固定して渡します。この記事では、入れ方、スキルの呼び分け、Federation・Router・Roverの各スキルが何を求めてくるか、同梱されるLSPとMCPの扱いを順に説明します。

apollo-skillsプラグインの中身

プラグインの提供元はApollo GraphQLで、ライセンスはMITです。マニフェストの名前は apollo-skills、マーケットプレイス名は apollo-marketplace です。マーケットプレイスの説明文は、Apollo Client、Server、Federation、Connectors、Router、Rover CLI、iOS、Kotlin、Apollo MCP Serverを対象にし、スキーマ設計・クエリ最適化・GraphQLのベストプラクティスを扱うとしています。

リポジトリの直下には、スキル本体の skills/ のほかに、.lsp.json と .mcp.json が置かれています。スキルだけでなく、言語サーバーとMCPサーバーの設定もまとめて入る構成です。

構成

プラグインが運ぶ3種類の部品

  • スキル

    skills/ 配下のSKILL.mdと参照ドキュメント。作業の手順と禁止事項を渡します。

  • LSP設定

    .lsp.json が graphql-lsp を起動し、.graphql などのファイルに言語サーバーをつなぎます。

  • MCP設定

    .mcp.json が graphos-tools という名前のHTTPサーバーを登録します。

導入手順

プラグインは専用のマーケットプレイス経由で入れます。Claude Codeのセッション内で、マーケットプレイスの追加とインストールを順に実行します。

/plugin marketplace add apollographql/skills
/plugin install apollo-skills@apollo-marketplace

GitHubリポジトリは owner/repo の形でマーケットプレイスとして追加できます。インストール後にパネルが再読み込みを求めたら、/reload-plugins を実行します。

シェルから入れたい場合は、同じ指定を claude plugin サブコマンドに渡します。

claude plugin marketplace add apollographql/skills
claude plugin install apollo-skills@apollo-marketplace

claude plugin install で入れたプラグインは、次にセッションを始めたときに読み込まれます。

プラグインを使わずにスキルだけ入れる方法

リポジトリのREADMEには、プラグイン以外の入れ方も載っています。

  • Skills CLI: npx skills add apollographql/skills で、対象のエージェントとスコープを対話で選ぶ
  • GitHub CLI: gh skill install apollographql/skills --agent claude-code(preview機能。--scope user で全プロジェクトに、--pin v1.0.0 でバージョン固定)

どちらもスキルだけを入れる経路です。LSPとMCPの設定まで欲しいなら、プラグイン経由を選びます。固定したバージョンは gh skill upgrade の対象から外れるため、更新の判断を自分で持てます。

スキルの呼び分け

プラグイン経由で入れたスキルは、名前空間付きのスラッシュコマンドになります。この記事で扱う3つを含め、READMEの一覧は次のとおりです。

コマンド用途
/apollo-skills:apollo-federation用途サブグラフのスキーマ設計
/apollo-skills:apollo-router用途Routerの設定と実行
/apollo-skills:rover用途スキーマ管理とローカル開発
/apollo-skills:graphql-schema用途スキーマ設計の指針
/apollo-skills:graphql-operations用途クエリ・ミューテーション・フラグメント
/apollo-skills:graphos-factory用途REST APIからConnectorsサブグラフを作る
/apollo-skills:apollo-mcp-server用途Apollo MCP Serverの設定

ほかにapollo-client、apollo-server、apollo-ios、apollo-kotlin、rust-best-practices、skill-creatorがあります。スキルは該当する作業を検知すると自動で働くとされ、明示的に呼ぶときだけスラッシュコマンドを使います。

apollo-connectors は非推奨で、graphos-factory に置き換わっています。READMEは、将来のリリースで削除されると書いています。Connectorsを扱うなら、最初から graphos-factory を選びます。

Federation: サブグラフの設計を任せる

apollo-federation スキルは、サブグラフのスキーマを書くための手順書です。呼ばれる場面は、新しいサブグラフを作るとき、@key でエンティティを定義するとき、@shareable や @override を使うとき、合成エラーを直すときです。

スキル本文は、Federation 2のスキーマが @link での宣言から始まることを前提にしています。

extend schema
  @link(url: "https://specs.apollo.dev/federation/v2.12",
        import: ["@key", "@shareable", "@external", "@requires", "@provides"])

これは公式のスキル本文にある形です。本文には、バージョンの v2.12 は説明用の値だと注記があります。コピーする前に、対応バージョンをFederationの変更履歴で確かめます。

スキルが決めている作法のうち、レビューで効くのは次の4点です。

  • 常にFederation 2.xの構文で書き、@link では使うディレクティブだけをimportする
  • すべてのサブグラフが同じ値を返す保証がないフィールドに @shareable を付けない
  • エンティティの識別は、単純なケースでは単一のID項目の @key を優先する
  • ローカルの合成検証には rover supergraph compose、本番スーパーグラフとの検証には rover subgraph check を使う

スキルのfrontmatterでは、許可ツールが Bash(rover:*)、Read、Write、Edit、Glob、Grepに限られています。Roverが入っていれば、設計から合成の確認まで同じ流れで回ります。

試す依頼の例

商品サービスと配送サービスのサブグラフがある状況で、次のように頼みます。

/apollo-skills:apollo-federation
shippingサブグラフのProductに、productsサブグラフのweightを使う
shippingEstimateフィールドを足して。合成まで確認して

このスキルの例では、外部フィールドを使う計算フィールドに @requires を使います。公式の例に沿えば、次のような形になります(例示であり、実際の出力とは限りません)。

type Product @key(fields: "id") {
  id: ID!
  weight: Int @external
  shippingEstimate: String @requires(fields: "weight")
}

Claudeの提案が @external と @requires の組になっているか、合成コマンドで確認まで進んだかを見れば、スキルが効いているかを判断できます。

Router: バージョンを先に決めさせる

apollo-router スキルの特徴は、設定を書く前に質問することです。Router v1とv2では、CORSやJWT認証、Connectorsの設定スキーマが非互換な箇所があるため、最初にターゲットのバージョンを選ばせます。

選択肢スキルの説明
Router v2.xスキルの説明推奨。現行のLTSで、Connectorsに必須
Router v1.xスキルの説明レガシー。サポート終了が告知され、セキュリティパッチのみ
分からないスキルの説明判断の目安を表示

続いて、本番か開発かを選びます。本番はイントロスペクション・サンドボックス・ホームページを切り、サブグラフのエラーを隠し、認証を必須にする設定です。開発は逆に開いた設定になります。

そのあと、JWT認証、CORS、操作の上限、トラフィック制御、テレメトリ、APQ、永続化クエリのセーフリスト、Connectors、サブスクリプション、ヘッダー伝播、レスポンスキャッシュの中から機能を選びます。

設定を書く前に確認される点

セキュリティに関わる項目は、スキルが利用者に尋ねてから書く作りです。

  • CORSの許可オリジンは、本番でワイルドカード "*" を使わない
  • JWTの発行者は、v1が単数形の issuer、v2が複数形の issuers
  • 宣言的な認可(@authenticated / @requiresScopes / @policy)は、GraphOSに接続したRouterが前提
  • 永続化クエリのセーフリストはAPQと排他で、まず監査モード(log_unknown: true)で未登録の操作を確かめる
  • レスポンスキャッシュは、ユーザー固有のデータを返すサブグラフを先に尋ねる

操作の深さの上限は、Routerの既定が100で、スキルは50を出発点として示します。いきなり厳しくせず、warn_only: true で実トラフィックの深さを見てから絞る流れです。

既存の router.yaml がある場合、スキルはRouter v1からv2への自動移行コマンドも案内します。

router config upgrade router.yaml

許可ツールは、router、rover、curl、docker のBashコマンドと、Read・Write・Edit・Glob・Grepです。

Rover: スキーマの公開・検証とローカル開発

rover スキルは、GraphOSへのスキーマ公開、ローカルでのスーパーグラフ合成、rover dev による開発、check と lint での検証を扱います。スキル本文は、導入と認証から始まります。

npm install -g @apollo/rover
rover config auth
rover --version
rover config whoami

rover config auth の代わりに、環境変数 APOLLO_KEY にAPIキーを入れる方法もあります。グラフの指定は <GRAPH_ID>@<VARIANT> の形で、APOLLO_GRAPH_REF に入れておけば毎回の指定を省けます。

サブグラフの公開と検証は、次のコマンドです。

rover subgraph publish my-graph@production \
  --name products \
  --schema ./schema.graphql \
  --routing-url https://products.example.com/graphql
 
rover subgraph check my-graph@production \
  --name products \
  --schema ./schema.graphql

公開は本番のスキーマを変えます。check を先に通す順序を、CLAUDE.mdか依頼文で固定しておくと安全です。

グラフの中身を調べさせるときの型

エージェント向けに用意された手順もあります。グラフのスキーマを調べるときは、rover graph fetch の出力を rover schema にパイプします。

rover graph fetch my-graph@production | rover schema describe -
rover graph fetch my-graph@production | rover schema search - "shipping"

スキルが定める規則は3つです。

  • rover supergraph fetch ではなく rover graph fetch を使う(前者は join__ などFederation内部の定義を含む合成SDLを返す)
  • 取得したSDLを単独で出力して読ませず、必ずパイプに流す。巨大なスキーマでコンテキストが埋まるのを避けるため
  • rover schema describe と rover schema search はグラフ参照でなくSDLを受け取る。rover schema describe my-graph@production は失敗する

同梱のLSPとMCPをどう扱うか

GraphQLの言語サーバー

.lsp.json は、graphql-lsp server -m stream を起動し、.graphql・.gql・.graphqls に結びつけます。再起動の上限は3回です。

Claude Codeのプラグイン仕様では、LSP設定の command は言語サーバーのバイナリを指します。graphql-lsp が実行できる状態かは、導入後に一度確かめます。スキルの利用はLSPと独立しているため、言語サーバーが未導入でもスキルは使えます。

GraphOS MCPサーバー

.mcp.json は、graphos-tools という名前で https://mcp.apollographql.com をHTTPサーバーとして登録します。プラグインを入れると、このMCPもセットで有効になります。

ホスト型のGraphOS MCPサーバー自体の認証や、書き込み系ツールの線引きは別の話題です。ClaudeとApollo GraphOS MCPをつなぐ手順にまとめています。スキル(手順書)とMCP(実行手段)は役割が違い、前者は「どう書くか」、後者は「グラフに何をするか」を担当します。

プラグインがコンテキストに載せる分量が気になるときは、claude plugin detailsでの測り方が使えます。導入済みの一覧はclaude plugin list --jsonで棚卸しできます。

使い分けの目安

作業呼ぶスキル先に用意するもの
サブグラフのスキーマを書く呼ぶスキルapollo-federation先に用意するものRoverがあると合成まで確認できる
router.yamlを作る・移行する呼ぶスキルapollo-router先に用意するもの対象のRouterバージョン、本番か開発か
スキーマを公開・検証する呼ぶスキルrover先に用意するものAPOLLO_KEY、APOLLO_GRAPH_REF
RESTをサブグラフにする呼ぶスキルgraphos-factory先に用意するものREST API(OpenAPI仕様は任意)
型・命名・ページネーションを見直す呼ぶスキルgraphql-schema先に用意するもの対象スキーマ

graphos-factory は、初回の使用時に約3MBの graphos-factory バイナリを、同梱するリリースからダウンロードします。ダウンロードが発生する点は、ネットワーク制限のある環境で先に知っておく価値があります。

プラグインを入れても、設計の判断はこちらに残ります。@shareable を付けてよいかや、Routerのキャッシュにどのデータを載せてよいかは、サービスの中身を知る人が決めることです。スキルは、その判断を聞き忘れないための手順として使うのが向いています。

この記事を共有:XはてブLinkedIn

関連する記事

Claude Code をもっと見る →