G-gen の福井です。当記事では、AI エージェントツールに専門知識やワークフローを追加するためのオープンフォーマットである Agent Skills について、概念や動作の仕組み、スキルの構造、使い方などを解説します。 概要 Agent Skills とは Skills が可能にすること Skills の実体 Agent Skills の仕組み 基本的な動作 コンテキスト肥大化の防止 Skills と MCP の関係 Skills の構造 ディレクトリ構成 SKILL.md の中身 使い方 対応ツール Skills ファイルの配置場所 インストール Gemini CLI からスキルを呼び出してみる 概要 Agent Skills とは Agent Skills は、生成 AI エージェントツールに専門知識やワークフローを追加するためのオープンフォーマットです。Anthropic が策定したオープンスタンダードであり、現在は Anthropic 社外のさまざまなツールでも採用が進んでいます。 Agent Skills は、Claude Code、Gemini CLI など、さまざまな AI エージェントツールで使用することができます。 なお当記事内では、文脈に応じて Agent Skills のことを「スキル」「Skill（s）」と表記する場合があります。 参考 : https://agentskills.io/ 参考 : Agent Skills - Claude API Docs 参考 : Agent Skills | Gemini CLI Skills が可能にすること Agent Skills が提供する典型的な能力としては、以下のようなものが挙げられます。 特定領域の専門知識（例: Google Cloud の各製品の正確な仕様や最新の API） 繰り返し実行されるワークフロー（例: コードレビューの観点、リリース手順） 組織やチーム固有のルール（例: 社内のコーディング規約、ドキュメントテンプレート） AI エージェントツールは、Agent Skills を必要なときにだけ読み込むので、LLM のコンテキストウインドウを不必要に圧迫することがありません。 システムインストラクション（システムプロンプト）や tools を必要なときにだけ読み込むことで、 コンテキストウインドウを効率的に使用できるようにする のが Agent Skills の最大のメリットといえます。 Skills の実体 Agent Skills の実体は、 SKILL.md というマークダウン形式のテキストファイルを含む 1 つのフォルダ（ディレクトリ）です。フォルダの中には SKILL.md に加えて、参照ドキュメントや実行スクリプトなどのアセットを任意で配置できます。 AI エージェントツールはこのフォルダをスキルとして認識し、必要に応じて読み込んで使用します。 Agent Skills と AI エージェントツールの関係 Agent Skills の仕組み 基本的な動作 Agent Skills は、 progressive disclosure （段階的開示）と呼ばれる仕組みで動作します。これは、必要なときに必要な情報だけを読み込むことで、AI エージェントツールのコンテキストを効率的に使うための仕組みです。 progressive disclosure では、AI エージェントツールはスキルを次の 3 段階に分けて読み込みます。 1 つ目の段階は Discovery （発見）です。AI エージェントツールの起動時に、使用可能なすべてのスキルの name（名前）と description（説明文）だけを読み込みます。この段階では、各スキルがどのような場面で使えるのかを把握するための最小限の情報のみが読み込まれます。 2 つ目の段階は Activation （有効化）です。ユーザーからのタスクが、あるスキルの description にマッチした場合、AI エージェントツールはそのスキルの SKILL.md 本文をすべて読み込みます。これにより、そのスキルに書かれた指示の詳細をタスク遂行に使用できます。 3 つ目の段階は Execution （実行）です。AI エージェントツールは SKILL.md の指示に従ってタスクを進めます。必要に応じて、スキルに同梱されたスクリプトを実行したり、参照ドキュメントを追加で読み込んだりします。 progressive disclosure の 3 段階 このように、すべての情報を一度に読み込むのではなく、必要な情報を必要なタイミングだけ読み込む仕組みであるため、多数のスキルを導入した場合でも、LLM のコンテキストウインドウを節約できます。 コンテキスト肥大化の防止 Agent Skills が解決しようとしている課題の 1 つに、AI エージェントツールに特有の コンテキスト肥大化 （Context Bloat）があります。 AI エージェントツールが特定領域で正確に動作するためには、LLM が正確な知識を参照する必要があります。必要な情報を AI に参照させるには、システムインストラクションやユーザープロンプトとして大量の情報を読み込ませたり、あるいは Model Context Protocol（MCP）サーバー経由でドキュメントを取得させるといった方法が挙げられます。例えば Google は、Google Cloud のドキュメントを提供する MCP サーバーを公開しています。 しかし、長大なプロンプトや MCP サーバーによる情報取得を多用すると、大量のドキュメントが常時、コンテキストウィンドウに読み込まれることになり、LLM の応答精度や応答速度が下がるほか、トークン消費量の増加にも繋がります。これがコンテキスト肥大化です。 一方、Agent Skills では、AI エージェントツールが、 必要なスキルだけを必要なタイミングで 読み込みます。これにより、コンテキストを節約しつつ、特定領域に関する正確な知識を LLM に与えることができます。 Skills と MCP の関係 前のセクションでも触れた MCP は、外部システムへのアクセスを標準化するためのプロトコルです。一方の Agent Skills は、専門知識やワークフローをパッケージ化して AI エージェントツールに配信するためのフォーマットです。両者は競合するものではなく、 役割が異なる補完的な関係 です。 MCP は、LLM が外部のシステムやデータソースにアクセスする手段を提供します。たとえば、Google ドライブのファイルを読み込む、データベースにクエリを発行する、Slack にメッセージを投稿する、といった操作を、LLM が API 経由で実行しやすくするプロキシのような役割を果たすのが MCP です。 一方の Agent Skills は、AI エージェントツールが特定の領域やタスクで、人間の意図どおりに振る舞うための知識と手順（プロンプト）や、tools（スクリプト等）をパッケージしたものです。Agent Skills の実体は 1 つのディレクトリにまとめられたファイル群であるため、1 度開発すれば容易に他人に共有できます。また、スキル内からは、同梱のスクリプトをツールとして使うこともできれば、MCP サーバーを呼び出すこともできます。 Agent Skills と MCP は 併用 できます。たとえば、組織の開発のワークフローに沿うために以下のような Agent Skills を作成できます。 ユーザーが指示した CSV ファイルを分析し、適切な BigQuery テーブルの設計を行う（パーティショニング、クラスタリング、カラムの説明などを作成） BigQuery 用の MCP サーバーを呼び出して、設計に基づいてテーブルを作成する CSV を新規のテーブルにロードする Skills の構造 ディレクトリ構成 Agent Skills は、 SKILL.md を必須ファイルとして含む 1 つのフォルダで構成されます。 SKILL.md 以外のファイルやフォルダは、用途に応じて任意で配置できます。 代表的なディレクトリ構成は以下のとおりです。 skill-name/ ├── SKILL.md （必須）スキルのメタデータと指示 ├── references/ （任意）詳細な参照ドキュメント ├── scripts/ （任意）スキルから呼び出される実行スクリプト └── assets/ （任意）テンプレートやリソース それぞれのファイルやフォルダの役割は、以下の通りです。 構成要素 必須/任意 役割 SKILL.md 必須 スキルのメタデータと、AI エージェントツールがタスクを遂行する際に従う指示を記述するファイル references/ 任意 SKILL.md の指示の中で参照される詳細なドキュメントを格納するフォルダ。AI エージェントツールは、SKILL.md の指示に従って必要なときだけ読み込む scripts/ 任意 スキルから呼び出される実行可能なスクリプトを格納するフォルダ。フォーマット変換スクリプトや API 呼び出しのヘルパースクリプトなどを配置する assets/ 任意 スキルが使用するテンプレートファイルやリソース（画像、設定ファイルなど）を格納するフォルダ シンプルなスキルであれば SKILL.md だけで構成することも可能ですし、複雑なスキルであれば references/ や scripts/ を組み合わせて表現できます。スキルの複雑さに応じて柔軟に構成できる、軽量なフォーマットといえます。 参考 : Specification - Agent Skills SKILL.md の中身 SKILL.md は、先頭にメタデータを記述する YAML フロントマター（ファイルの冒頭に YAML 形式で記述されるメタデータのこと）があり、それに続いて、AI エージェントツールがタスクを遂行する際に従う指示を Markdown 形式で記述する構造になっています。 YAML フロントマターには、name（スキル名）と description（スキルの説明）の 2 つを必ず記述します。description は、AI エージェントツールがどのスキルを使うべきかを判断する際の最も重要な情報です。「このスキルがどのような場面で使われるべきか」を具体的に書きます。 google/skills リポジトリで公開されている bigquery-basics スキルの SKILL.md から、構造が分かる範囲を抜粋して以下に示します。 参考 : google/skills - bigquery-basics/SKILL.md （Apache 2.0 ライセンス、抜粋） --- name: bigquery-basics description: >- Manages datasets, tables, and jobs in BigQuery, and integrates with BigQuery ML and Gemini for advanced data analytics and AI-driven insights. Use when you need to interact with BigQuery, run SQL queries, manage BigQuery resources, or leverage BigQuery's built-in ML capabilities. Also use when performing data analysis, ingesting data into BigQuery, or developing AI applications on BigQuery. --- # BigQuery Basics BigQuery is a serverless, AI-ready data platform that enables high-speed analysis of large datasets using SQL and Python. Its disaggregated architecture separates compute and storage, allowing them to scale independently while providing built-in machine learning, geospatial analysis, and business intelligence capabilities. ## Setup and Basic Usage （中略) ## Reference Directory - [ Core Concepts ]( references/core-concepts.md ): Storage types, analytics workflows, and BigQuery Studio features. - [ CLI Usage ]( references/cli-usage.md ): Essential ` bq ` command-line tool operations for managing data and jobs. - [ Client Libraries ]( references/client-library-usage.md ): Using Google Cloud client libraries for Python, Java, Node.js, and Go. （以下省略） このサンプルから、YAML フロントマター（ name と description ）、Markdown 本文（ # BigQuery Basics 以降）、 references/ 配下のファイルへの参照（ ## Reference Directory ）という、これまで説明してきた構造が実際にどう書かれているかを確認できます。 description には、「いつこのスキルを使うか」を具体的に書くことが重要です。AI エージェントツールは、起動時に全スキルの description を読み込み、ユーザーのタスクと照合して「どのスキルを使うか」を判断します。description が曖昧だと、本来使われるべきスキルが選ばれない、または不適切な場面で使われてしまう、といった問題が発生します。 bigquery-basics スキルの description を見ると、「Use when you need to interact with BigQuery, run SQL queries...」のように、「いつ使うか」が具体的な動詞で複数列挙されているのが分かります。これにより、AI エージェントツールがユーザーのタスクと正確にマッチングできるようになっています。 使い方 対応ツール 規格に準拠した AI エージェントツールであれば、開発元を問わず Agent Skills を使用できます。主要なツールは以下のとおりです。 ツール名 提供元 種別 Antigravity Google IDE Gemini CLI Google CLI Claude Code Anthropic CLI Cursor Anysphere IDE GitHub Copilot GitHub IDE 拡張 Codex OpenAI CLI Anthropic、Google、OpenAI、GitHub などの主要 AI ベンダーが提供するツールが揃って Agent Skills の規格に対応しており、特定ベンダーに閉じない普遍的なフォーマットとして広く採用されていることがわかります。 なお、後述する npx skills install コマンドは、2026年5月現在で合計 55 個の AI エージェントツールへのインストールに対応しています。 Skills ファイルの配置場所 スキルは、決められたディレクトリに配置することで認識されます。AI エージェントツールは、起動時にこのディレクトリ配下を走査して、スキルを検出します。 Agent Skills の規格では、配置場所として Workspace スコープ と User スコープ の 2 種類が定義されています。 スコープ 説明 用途 Workspace スコープ プロジェクト（リポジトリ）単位でスキルを配置する形式。プロジェクトのカレントディレクトリ配下に配置され、プロジェクトと一緒に Git 管理できる プロジェクトメンバー間でスキルを共有する場合に使用する User スコープ ユーザー単位でスキルを配置する形式。ホームディレクトリ配下に配置され、すべてのプロジェクトから横断的に使用できる 個人で使うスキルや、プロジェクトを問わず使用するスキルに適している 主要なツールごとの、各スコープの配置場所は以下のとおりです。 ツール名 Workspace スコープ User スコープ Universal（Antigravity、Gemini CLI、Cursor 等に共通） .agents/skills/ ~/.agents/skills/ Gemini CLI .gemini/skills/ ~/.gemini/skills/ Claude Code .claude/skills/ ~/.claude/skills/ Augment .augment/skills/ ~/.augment/skills/ AiderDesk .aider-desk/skills/ ~/.aider-desk/skills/ 上記の表で「Universal」としているのは、複数のツールで使用される配置場所のことです。Antigravity、Gemini CLI、Cline、Codex、Cursor、GitHub Copilot などは、共通の .agents/skills/ ディレクトリ配下に配置されたスキルを認識します。 一方、Claude Code や Augment、AiderDesk など、独自のディレクトリを持つツールは、それぞれ専用のディレクトリにスキルを配置する必要があります。 なお、Gemini CLI については、上記の Universal エイリアス（ .agents/skills/ ）に加えて、ツール固有のパスである .gemini/skills/ も同時にサポートしています。両者は併用可能で、Gemini CLI は起動時に両方のディレクトリを走査します。同一スコープ（Workspace スコープまたは User スコープ）内で同名のスキルが両方のディレクトリに存在する場合は、 .agents/skills/ 配下のスキルが優先される仕様です。 参考 : Gemini CLI | Agent Skills Discovery tiers インストール 自前で作成したスキルを使用する場合は、前述に示したディレクトリに、 SKILL.md を含むスキルフォルダを直接配置します。AI エージェントツールは起動時に該当ディレクトリを走査してスキルを検出するため、特別なインストール作業は不要です。社内向けのスキルや、自身で作成したスキルを使う場合はこの方法が適しています。 一方、GitHub などで公開されているスキルは、 npx skills install コマンドでインストールできます。 npx skills は、Vercel 社（Vercel Labs）が提供するオープンソースの CLI ツールです。GitHub リポジトリ上の SKILL.md を取得し、AI エージェントツールの所定の配置場所に展開する役割を担います。 参考 : vercel-labs/skills - GitHub なお、 npx コマンドは Node.js に同梱されているコマンド実行ツールです。Node.js は、JavaScript ベースのコマンドラインツールやスクリプトを動かすためのランタイム環境で、Windows、macOS、Linux のすべてに対応しています。手元の環境で npx コマンドが使えない場合は、まず Node.js をインストールしてください。 参考 : Node.js 公式サイト - ダウンロード 以下のように GitHub リポジトリの URL を指定してコマンドを実行することで、スキルを導入できます。ここでは Google が公開している公式リポジトリ google/skills を例に挙げます。 npx skills install github.com/google/skills 処理を続行するか問われるため「y」を入力します。 Need to install the following packages: skills@ 1 . 5 . 5 Ok to proceed? ( y ) y インストールするスキルを選択します。リポジトリに含まれるスキルが一覧で表示されるため、必要なものだけを選択できます。 ┌ skills │ ◇ Source: https://github.com/google/skills.git │ ◇ Repository cloned │ ◇ Found 13 skills │ ◆ Select skills to install ( space to toggle ) │ ◻ alloydb-basics │ ◼ bigquery-basics ( Manages datasets, tables, and jobs in BigQuery, and integ... ) │ ◻ cloud-run-basics │ ◻ cloud-sql-basics │ ◻ firebase-basics │ ◼ gemini-api ( Guides the usage of the Gemini API on Agent Platform with... ) │ ◻ gke-basics │ ◼ google-cloud-recipe-auth ( Provides expert guidance on authenticating and authorizin... ) │ ◼ google-cloud-recipe-networking-observability ( Investigates Google Cloud networking issues by analyzing ... ) │ ◼ google-cloud-recipe-onboarding ( Guidance for a developer ' s first steps on Google Cloud, c...) │ ◼ google-cloud-waf-cost-optimization (Generates cost optimization guidance for Google Cloud wor...) │ ◼ google-cloud-waf-reliability (Generates reliability-focused guidance for Google Cloud w...) │ ◼ google-cloud-waf-security (Generates security-focused guidance for Google Cloud work...) インストール対象の AI エージェントツールを選択します。 Universal (.agents/skills) の下部に記載されているツールは、いずれも .agents/skills ディレクトリに配置されたスキルを認識します。一方、Claude Code など独自の配置場所を持つツールは、Additional agents の一覧から個別に選択する必要があります。 ◇ 55 agents ◆ Which agents do you want to install to? │ │ ── Universal ( .agents/skills ) ── always included ──────────── │ • Amp │ • Antigravity │ • Cline │ • Codex │ • Cursor │ • Deep Agents │ • Dexto │ • Firebender │ • Gemini CLI │ • GitHub Copilot │ • Kimi Code CLI │ • OpenCode │ • Warp │ │ ── Additional agents ───────────────────────────── │ Search: │ ↑↓ move, space select, enter confirm │ │ ○ AiderDesk ( .aider-desk/skills ) │ ○ Augment ( .augment/skills ) │ ○ IBM Bob ( .bob/skills ) │ ❯ ○ Claude Code ( .claude/skills ) │ ○ OpenClaw ( skills ) │ ○ CodeArts Agent ( .codeartsdoer/skills ) │ ○ CodeBuddy ( .codebuddy/skills ) │ ○ Codemaker ( .codemaker/skills ) │ ↓ 32 more │ │ Selected: Amp, Antigravity, Cline + 10 more 次に、インストールのスコープを選択します。 Project はカレントディレクトリ配下にスキルを配置する形式で、プロジェクトと一緒に Git 等で管理できます。Global はホームディレクトリ配下にスキルを配置する形式で、すべてのプロジェクトから横断的に使用できます。プロジェクトごとに使うスキルが異なる場合は Project、すべてのプロジェクトで共通して使う場合は Global を選びます。 ◆ Installation scope │ ● Project ( Install in current directory ( committed with your project )) │ ○ Global インストール確認に対する承認を行うため「Yes」を選択します。 インストール内容に加えて、各スキルに対する Gen、Socket、Snyk によるセキュリティリスク評価が表示されます。Agent Skills は AI エージェントツールが持つ権限で実行されるため、信頼できるソースのスキルだけをインストールすることが重要です。セキュリティリスク評価を確認することで、インストール前にリスクを把握できます。 セキュリティリスク評価に関する詳細は、 Security Risk Assessments の Details のリンク先から確認できます。 ◇ Installation Summary ──────────────────────────────────────────────────────────────────╮ │ │ │ ~/blog_work/google-skills/.agents/skills/bigquery-basics │ │ copy → Amp, Antigravity, Cline, Codex, Cursor + 8 more │ │ │ │ （中略） │ │ │ ├─────────────────────────────────────────────────────────────────────────────────────────╯ │ ◇ Security Risk Assessments ──────────────────────────────────────────────────────────╮ │ │ │ Gen Socket Snyk │ │ bigquery-basics Safe 0 alerts Low Risk │ │ gemini-api Safe 0 alerts Med Risk │ │ （中略） │ │ │ │ Details: https://skills.sh/google/skills │ │ │ ├──────────────────────────────────────────────────────────────────────────────────────╯ │ ◆ Proceed with installation? │ ● Yes / ○ No インストールが完了します。 └ Done! Review skills before use; they run with full agent permissions. Vercel 社が公開している「find-skills」のインストール確認があります。今回は不要ですので「No」を選択します。 ◆ Install the find-skills skill? It helps your agent discover and suggest skills. │ ○ Yes / ● No Gemini CLI からスキルを呼び出してみる これまで解説してきた Agent Skills の仕組みが実際にどう機能するかを、 Gemini CLI を例にとって実演します。 Gemini CLI の概要やインストール方法については、以下の記事で詳しく解説しています。 blog.g-gen.co.jp 今回は、題材として google/skills リポジトリで公開されている bigquery-basics スキルを使用します。ここからは、すでにこのスキルが導入済みである前提で紹介します。 参考 : google/skills - bigquery-basics/SKILL.md （Apache 2.0 ライセンス、抜粋） bigquery-basics スキルが導入された Gemini CLI に対して「BigQuery のデータセットを作りたい」と入力した結果が以下です。 > BigQuery のデータセットを作りたい BigQuery Dataset Creation Research: Activating the BigQuery skill to assist with dataset creation. ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ Action Required │ │ │ │ ? Activate Skill "bigquery-basics": Manages datasets, tables, and jobs in BigQuery, and integrates with BigQuery ML and Gemini for advanced data analytics and AI-driven insights. Use when … │ │ │ │ You are about to enable the specialized agent skill bigquery-basics. │ │ │ │ Description: │ │ Manages datasets, tables, and jobs in BigQuery, and integrates with BigQuery ML and Gemini for advanced data analytics and AI-driven insights. Use when you need to interact with BigQuery, │ │ run SQL queries, manage BigQuery resources, or leverage BigQuery's built-in ML capabilities. Also use when performing data analysis, ingesting data into BigQuery, or developing AI │ │ applications on BigQuery. │ │ │ │ Resources to be shared with the model: │ │ Showing up to 200 items (files + folders). │ │ │ │ /home/xxx/blog_work/google-skills/.agents/skills/bigquery-basics/ │ │ ├───SKILL.md │ │ └───references/ │ │ ├───cli-usage.md │ │ ├───client-library-usage.md │ │ ├───core-concepts.md │ │ ├───iac-usage.md │ │ ├───iam-security.md │ │ └───mcp-usage.md │ │ Do you want to proceed? │ │ │ │ ● 1. Allow once │ │ 2. Allow for this session │ │ 3. No, suggest changes (esc) │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ ここで起こっているのは、progressive disclosure の Activation（有効化）の段階です。Gemini CLI は起動時に全スキルの description を読み込んでおり（Discovery）、ユーザーのプロンプト「BigQuery のデータセットを作りたい」が bigquery-basics スキルの description にマッチしたため、 SKILL.md 本文を読み込もうとしています。 ユーザーが有効化を承認すると、Gemini CLI は bigquery-basics スキルの SKILL.md を読み込み、その指示に従ってタスクを進めます。ここから progressive disclosure の Execution（実行）の段階です。 SKILL.md の指示に基づいて、データセット作成に必要な情報を Gemini CLI が対話形式で確認してきます。最初に、データセット名を尋ねられます。今回は my_dataset と入力します。 ╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ Answer Questions │ │ │ │ ← ✓ Dataset Info │ □ Location │ ≡ Review → │ │ │ │ データセット名は何にしますか？ │ │ │ │ > my_dataset │ │ │ │ │ │ Enter to submit · Tab/Shift+Tab to switch questions · Esc to cancel │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ 続いて、データセットを作成するロケーション（リージョン）を尋ねられます。US や EU といったマルチリージョンに加えて、asia-northeast1（東京リージョン）などの選択肢が提示されます。今回は asia-northeast1 を選択します。 ╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ Answer Questions │ │ │ │ ← ✓ Dataset Info │ □ Location │ ≡ Review → │ │ │ │ ロケーション（リージョン）はどこにしますか？ │ │ │ │ ▲ │ │ 1 . US │ │ US multi-region │ │ 2 . EU │ │ EU multi-region │ │ ● 3 . asia-northeast1 │ │ Tokyo region │ │ ▼ │ │ │ │ Enter to select · ←/→ to switch questions · Esc to cancel │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ 入力した情報の確認画面が表示されます。データセット名 my_dataset 、ロケーション asia-northeast1 で問題ないため、そのまま確定します。 ╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ Answer Questions │ │ │ │ ← ✓ Dataset Info │ ✓ Location │ ≡ Review → │ │ │ │ Review your answers: │ │ │ │ Dataset Info → my_dataset │ │ Location → asia-northeast1 │ │ │ │ Enter to submit · Tab/Shift+Tab to edit answers · Esc to cancel │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ 入力した情報を元に、Gemini CLI が実行すべき gcloud コマンドと bq コマンドが提示されました。ここでは、BigQuery API の有効化（ gcloud services enable bigquery.googleapis.com ）とデータセット作成（ bq mk --dataset --location=asia-northeast1 my_dataset ）を 1 行で実行する形になっています。コマンドの実行を承認します。 ╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ ? Shell gcloud services enable bigquery.googleapis.com && bq mk --dataset --location = asia-northeast1 my_dataset │ │ ╭────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╮ │ │ │ gcloud services enable bigquery.googleapis.com && bq mk --dataset --location = asia-northeast1 my_dataset │ │ │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ │ │ Allow execution of [ gcloud ] ? │ │ │ │ ● 1 . Allow once │ │ 2 . Allow for this session │ │ 3 . No, suggest changes ( esc ) │ ╰────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────────╯ コマンドが実行され、BigQuery のデータセットが作成されました。Gemini CLI から、データセットの作成完了と次のステップの提案が返ってきます。 ✦ BigQuery のデータセット my_dataset を asia-northeast1（東京）リージョンに作成しました。 次のステップとして、テーブルの作成やデータのインポートなど、お手伝いできることはありますか？ このように、Agent Skills の仕様に準拠したスキルは、AI エージェントツールが認識できる場所に配置されていれば、ユーザーがスキルを意識して呼び出すことなく、ユーザーのプロンプトに応じて自動的に起動します。「Discovery」「Activation」「Execution」の 3 段階を経て動作する progressive disclosure の仕組みが、Gemini CLI で実際に動作していることが確認できました。 福井 達也 (記事一覧) カスタマーサクセス課 エンジニア 2024年2月 G-gen JOIN 元はアプリケーションエンジニア(インフラはAWS)として、PM/PL・上流工程を担当。G-genのGoogle Cloudへの熱量、Google Cloudの魅力を味わいながら日々精進

こんにちは。ワンキャリアで、データサイエンティストをしている申です。 私はもともと、小売・金融・旅行業向けのシステム開発に携わっていました。金融系のトランザクション処理や旅行予約の在庫管理など、止まったら即アウトの領域です。 前職でデータサイエンティストへと転身し、現在はワンキャリアでデータ分析や AI・機械学習モデルの開発を中心に取り組んでいます。

はじめに こんにちは、データ基盤ブロックの平本（ @cisetn ）です。 本記事では、ZOZOTOWNのリアルタイムデータ連携基盤の中核である ETL層 を作り直した事例を紹介します。対象はオンプレミスのSQL ServerからBigQueryへリアルタイムにデータを連携する基盤です。そのETL層を Goで実装したプラグイン （実行基盤はFluent Bit）で再設計しました。 ZOZOのリアルタイム連携基盤は2020年に 一度紹介記事を公開しています が、それ以降、段階的にアーキテクチャを見直してきました。本記事はその中でもETL層の再設計にフォーカスします。 想定読者は、リアルタイム連携基盤やストリーミング処理基盤の設計・運用に関わる方です。 本記事で扱うこと、扱わないことは次のとおりです。 扱う ：ZOZOのリアルタイム連携の全体像、今回リプレイスした基盤の背景・設計・実装 扱わない ：BigQuery側のテーブル設計、SQL Server側のChange Tracking設定、利用側（BI・分析クエリ等） 目次 はじめに 目次 ZOZOのリアルタイムデータ連携の全体像 これまでの変遷 リプレイスに至った背景 顕在化してきた課題 新基盤アーキテクチャ 設計の軸 技術選定：Fluent Bit + Goプラグイン 全体構成 大量のデータをリアルタイムで捌くために考えたこと 新基盤の構成 INPUT内部：取得とエンコードを分けた OUTPUT内部：送信とACK確認を分けた 結果 今後の展望：Change Data Captureへの移行 まとめ ZOZOのリアルタイムデータ連携の全体像 本題の前に、ZOZOにおけるリアルタイム連携の全体像を軽く俯瞰しておきます。本記事のテーマがあくまで「その中のひとつ」であることを共有するためです。 ZOZOではデータソースが多岐にわたります。オンプレミスのものもあれば、クラウド上のものもあり、MySQL、SQL Server、DynamoDBなどさまざまです。当然、差分を検知する手段もソースに応じて変わりますし、連携の実現方式も1つではありません。 マネージド / SaaSで済むケース ：例えばMySQL → BigQueryであれば Datastream を利用する 専用のパイプラインを組む必要があるケース ：例えばDynamoDB → BigQueryのように、対応するマネージドサービスがない場合は、別途データ連携のパイプラインを構築する必要がある 結果として、ZOZOのリアルタイム連携基盤は 複数系統に分かれて共存 しています。本記事で扱うのは、そのうち オンプレ SQL Server → BigQuery の系統です。本番環境（prd）で 約400のテーブル を連携対象としており、新規の連携依頼も日々発生するため、データ基盤の運用において比重の大きな系統となっています。SQL ServerのChange Tracking機能で変更を検知し、プラグインで取得したレコードをPub/Sub経由でBigQueryに流しています。 これまでの変遷 実は、本記事で扱う系統は今回が初めてのリプレイスではありません。以下の変遷を経ています。 時期 アーキテクチャ 主目的 2020 Qlik Replicate → fluentd + Dataflow → BigQuery 安定性向上 + コスト削減 2024 fluentd + BigQuery Subscription （Dataflow を廃止） コスト削減 2025 プラグインによる ETL 層の再設計 + BigQuery Subscription 効率改善（メモリ・スループット・コスト） 2024年には、ストリーム処理層のDataflowを廃止し、Pub/SubのBigQuery Subscriptionに置き換えるリプレイスが行われました。このフェーズの主目的はコスト削減です。 そして今回、ETL層をプラグインで再設計したのが本記事のテーマです。詳細な背景と目標は次章で述べますが、結果として、コスト削減・メモリ効率の改善・スループット向上・運用課題の解消といった効果につながりました（数値は末尾）。 リプレイスに至った背景 誤解のないよう先に述べておくと、旧基盤の設計が「悪かった」わけではありません。2020年当時、ZOZOのデータ基盤はまさに拡大していくフェーズにあり、リアルタイム連携の需要も増え始めたばかりでした。そうした状況では、プラグインが豊富なfluentdとDataflowのように既存のツールを組み合わせて素早く構築できる構成は合理的な選択だったかと思います。実際、信頼性（データ欠損が起きないこと）は チェックポイント機構 などによって担保できており、長く運用されてきました。チェックポイント機構は、処理済みのChange TrackingバージョンをBigQueryに保持する仕組みです。Pod再起動時はそこから再開できます。 顕在化してきた課題 一方で、運用を続け、データ量や利用要件が増えていく中で、 効率の側面 でいくつかの課題が徐々に顕在化してきました。 メモリ効率 ：結果セットを一括でメモリに載せる実装のため、メモリ使用量がデータ量に比例して増加する構造でした。大量更新時のOOMを避けるためには「ピーク時のデータ量」を見越した大きなメモリを常時確保しておく必要があり、データ量が増えるにつれてリソース見積もりの難しさが目立つようになってきました。 コスト ：上記のメモリ確保がそのままコストに直結します。メモリがトランザクション単位のデータ量に比例する構造であるかぎり、「ピーク時のデータ量」の見積もりを下回るとOOM直行となります。そのため運用上の工夫（時間帯別のスケーリング等）では本質的な改善が難しく、リソースの常時確保によるコスト増を抱え続けるしかありませんでした。 性能 ：逐次処理ベースの実装のため、1トランザクションあたりの規模が大きいテーブルでは、リアルタイム性を保ちにくい場面もありました。 運用 ：依存していたコンテナイメージがEOLを迎えており、継続利用にリスクがありました。加えて、内部状態の可視性が低く、障害発生時の原因特定にも時間がかかる状況でした。 一言でまとめると、各所でガタが出始めており、信頼性を維持したまま効率（メモリ・スループット・コスト）の側面を改善するため、リプレイスを検討するタイミングに来ていた、ということです。 新基盤アーキテクチャ 設計の軸 新基盤の設計指針はシンプルで、 キャパシティプランニングの軸を「ピーク時のデータ量」から「単位時間あたりの処理量」に変える ことに尽きます。信頼性（データ欠損が起きないこと）は旧基盤からチェックポイント機構によって担保されており、新基盤でもそのまま引き継いでいます。そのため本記事のテーマは 信頼性を維持したまま、効率（メモリ・スループット・コスト）をどう改善したか です。 技術選定：Fluent Bit + Goプラグイン 今回のリプレイスは、前フェーズ（2024年のDataflow撤廃 + BigQuery Subscriptionへの切り替え）の延長線上にあります。前フェーズで Dataflow関連の費用がまるごと不要になり大きなコスト削減は既に達成済み で、下流（Pub/Sub HubとBigQuery Subscription）も整理されている状態でした。一方でETL層はfluentdベースのまま残っており、メモリ効率とスループットの面で課題が顕在化していたため、今回はその続きとして ETL 層の中身を作り直す ことにしました。下流はそのまま踏襲し、ソース側（Change Tracking設定）にも手を加えません。 このスコープと、既存のPub/Sub Hub構成・BigQueryテーブル設計を維持する制約のもとで、マネージドCDCサービスやOSSのCDCミドルウェアの活用も検討しました。ただし我々のケースでは、既存テーブル設計とPub/Sub Hubへの直接出力をそのまま組み合わせ続けられる選択肢を見つけられず、プラグインとして実装する形に決めました。 採用したのは Fluent Bit + Goプラグイン です。決め手は次のとおりでした。 既存基盤がfluentdベースで運用されていたため、Fluent Bitへの移行が素直 ：プラグインモデル・設定構造・デプロイ手順といった運用ノウハウがそのまま活きる INPUT（Change Tracking取得）とOUTPUT（Pub/Sub送信）の挙動を 自分たちで細かく調整できる 。後述の非同期ACK並列確認のような最適化も、プラグインとして自前で書いているからこそ仕込める Fluent BitのBuffer・バックプレッシャー機構をそのまま活用できる Goプラグイン公式サポートにより、後述する並列処理をgoroutineとchannelで素直に書ける 全体構成 以下の図は主要コンポーネントのみを示した簡略図です。 ETL層（Fluent Bit + Goプラグイン）はGKE上で動作します。プラグインは データ取得（INPUT） と Pub/Subへの送信（OUTPUT） の2つで構成されており、それぞれの実装の詳細は次章で扱います。 大量のデータをリアルタイムで捌くために考えたこと 新基盤の設計で常に意識していたのは、「 大量のデータをいかにリアルタイムで捌くか 」という問いでした。データ量が増えてもパイプラインが詰まらず、メモリ消費がデータ量に比例しない構造をどう実装するかを検討しました。前章で述べた「単位時間あたりの処理量を軸にする」方針を、Fluent Bitのパイプライン上に乗せて具体化していった話を、本章で紹介します。 なお、Fluent Bitのパイプライン構造の全体像については、 公式ドキュメント もあわせてご覧ください。 新基盤の構成 Fluent Bitのパイプライン構造はINPUT → Filter → Buffer → Router → OUTPUTという形です。新基盤ではこのうち INPUTとOUTPUTをGoプラグインで実装 しました。チャンク単位の処理やバックプレッシャーといったBuffer周りの機構はFluent Bit Engineが標準で備えています。そのためプラグイン側は INPUTとOUTPUTの"箱の中"の設計に集中できました 。 設計の出発点として、データ取得から送信までの各処理を「どこがボトルネックになるか」で整理し、並列化方針を決めました。 処理 特性 並列化方針 CT取得（クエリ → カーソル） I/O bound（DB側） 単一スレッド（DBがボトルネック） エンコード CPU bound Worker数で並列化 Pub/Sub Publish I/O bound（NW） 非同期APIで並列化 ACK確認 I/O bound（NW待ち） 別Workerプールで並列化 CPU boundとI/O boundを別レーンに分け、それぞれを独立した並列度で動かす設計です。以下、INPUT内部・OUTPUT内部の順で紹介します。 INPUT内部：取得とエンコードを分けた INPUT内部の設計では、メモリとCPUを独立した軸として扱えるようにしました。 メモリの設計 ：結果セット全体を展開せず、 カーソルで小分けに読み進める方式 を採用。1回のクエリで読むレコード数 RecordsPerChunk をプラグインの設定で指定でき、本番では 10,000件/チャンク CPUの設計 ：取得処理とエンコード処理を 別レーンに分け 、エンコードは複数のWorkerで並列実行 取得とエンコードの間に 中間キュー（jobs queue） を挟むことで、取得側はエンコードの完了を待たずに次のチャンクを先行投入できます。キュー容量がゼロだと直列に戻ってしまうため、本実装では jobs queue の容量をWorker数の5倍 に設定しています。 この構造のもとで、同時にレコード形式でメモリに乗るチャンク数は NumWorkers × 6 個で頭打ちになります。内訳は「jobs queue上の最大 NumWorkers × 5 個 + 各Workerが処理中の1個」です。 同時メモリ上のレコード数 = RecordsPerChunk × (jobs queue + 処理中 Worker) = RecordsPerChunk × (NumWorkers × 5 + NumWorkers) = RecordsPerChunk × NumWorkers × 6 = 10,000 × NumWorkers × 6 例えばNumWorkers = 2なら、データ量に関わらず常に約12万レコード分のメモリしか確保しなくて済みます。100万件規模のトランザクションが流れてきても、結果セット全体を一括ロードしてしまう旧基盤と違ってOOMにはなりません。 なお、Fluent Bit上でカーソル方式を実装するときには工夫が必要でした。Fluent BitはINPUTに対して定期的に「データをちょうだい」と呼び出してくる構造になっており、素朴に書くと毎回新規にクエリを発行してしまいます。それでは結果セットが毎回頭から読み直されてしまうため、 カーソル状態をプラグイン側に持ち越し、呼び出しごとに「続きから」読み進める ようにしました。 OUTPUT内部：送信とACK確認を分けた OUTPUT内部では、 送信処理とACK確認処理を別レーンに分離 しました。Pub/SubのPublishは同期的に書くと「送信 → ACK待ち → 次へ」と直列化してしまい、ACK待ちのネットワークI/Oが支配的になります。これだとスループットがACKレイテンシに律速されてしまうため、両者を分離して並列化する方針を取りました。 送信側 ：非同期APIを呼んで即座にFuture相当の結果を受け取り、次へ進む。送信そのものは止まらない 確認側 ：受け取ったFutureのACK確認専用のWorkerプールを設け、複数並列で確認する 各メッセージが独立したACKタイムアウトを持つようになり、1件の遅延が後続全体を巻き込む連鎖タイムアウトを構造的に防げるようになりました。 このパターンはPub/Subに限らず、Future / Promiseを返す非同期メッセージングSDKで同様に当てはまる考え方です。 送信そのものではなく、ACK確認の方をスケールさせる という発想を、我々のケースでは設計時に組み込みました。 なお、下流の詰まりに対する保護（バックプレッシャー）はFluent Bit標準の機構が動いており、OUTPUT側で詰まったときにINPUTを自動で止める仕組みが標準で得られています。これがあるおかげで、プラグイン側は「並列にどんどん投げて確認する」シンプルな構造に保てました。 結果 前章で述べたカーソル方式により、メモリ消費はデータ量に依存しなくなりました。prd環境では、ETL Podを載せているGKEクラスタのTotal Memoryが 約240GiBから約40GiBへ、約1/6にまで縮小 し、ETLのGKEコストは約 -66％ 下がりました。 環境 リプレイス前 リプレイス後 削減率 prd $2,800 $940 -66% stg $3,200 $1,100 -67% 合計 $6,000 $2,000 -67% （2025年11月実績、ETLのGKEコストのみ・定価ベース） 注：stgはprdよりテーブル数が多く（stgは約500、prdは約400）、絶対額も大きくなっています。 性能面では、逐次処理からWorkerプールによる並列処理へ切り替えました。Worker数を変えるだけでスループットの線形拡張が可能な構造になりました。旧基盤では一部の大規模テーブルで遅延が長くなりやすく、監視の閾値を最大40分まで緩めて運用していました。新基盤では、全テーブル一律10分以内の閾値で安定処理しています。 運用面では、Fluent Bit標準のメトリクスにより内部状態が可視化されました。 fluentbit_input_records_total や fluentbit_output_retries_total などの指標を、GKEのMetrics Explorerから確認できます。実際、リプレイス後に予期せぬ問題が起きた際も、 fluentbit_output_retries_total の急増から原因を切り分けてデバッグできました。また、プラグインを自前で実装しているため、コアな部分まで踏み込んだ調査・修正も可能です。依存していたコンテナイメージのEOLリスクから解放された点も、得られた効果です。 今後の展望：Change Data Captureへの移行 現在はSQL Serverの Change Tracking (CT) を使っていますが、CTは「その行が変わった」ことは検知できても、変更前後の値や中間の変更履歴までは取得できません。 一方、SQL Serverには Change Data Capture (CDC) という、変更の全履歴を捕捉する機能もあります。今後はこのCTからCDCへの移行を視野に入れています。履歴を全て取得できれば、変更前後の差分分析や任意時点の状態再現など、分析側のユースケースを広げられます。 まとめ 本記事では、ZOZOTOWNのリアルタイムデータ連携基盤のETL層を、Fluent Bit + Goプラグインで作り直した事例を紹介しました。リアルタイムデータ連携基盤の設計や運用に取り組む方の参考になれば幸いです。 ZOZOでは、一緒にサービスを作り上げてくれる方を募集中です。ご興味のある方は、以下のリンクからぜひご応募ください。 corp.zozo.com