【調査レポ7】Google Antigravity SDKでAIが「専門スキル」を習得！skills_pathsとSKILL.mdによる外部ナレッジの読み込みを解説

Antigravity SDK入門 AI

前回の記事（調査レポ6）では、LocalAgentConfig の response_schema と Pydantic を組み合わせ、AIからの回答を型安全なオブジェクトとして取得する手法を解説しました。

AIエージェントの開発が進むにつれて直面する課題の一つが「プロンプトの肥大化とナレッジの保守性」です。システムプロンプト（system_instructions）に社内マニュアルや複雑な業務ルール、専門知識をすべて直接詰め込むと、コードが極めて長くなり保守・更新が困難になる傾向があります。

そこで今回は、当ブログの「Google Antigravity SDK 実践ロードマップ」でも予告していた応用機能である skills_paths と、スキル定義の核となる SKILL.md を活用し、AIエージェントに専門スキルや指示書を読み込ませる手法について確認していきます！

skills_paths と SKILL.md によるナレッジモジュール化とは？

skills_paths とは、LocalAgentConfig で設定できるパラメータの一つで、「外部に作成したスキル定義ファイル（SKILL.md）が格納されているディレクトリのパス」をAIエージェントに登録する機能です。

直接 Python コード内に長文プロンプトを書く場合と、skills_paths を使う場合の比較です。

  • 直接プロンプトに書き込む方法
    単一ファイルで完結する手軽さはありますが、マニュアルの修正時にPythonコード自体を書き換える必要があり、複数のエージェントで共通ルールを再利用しにくい懸念があります。
  • skills_paths + SKILL.md によるモジュール化
    専門知識や業務ルールを独立した Markdown ファイル（SKILL.md）で分離管理できます。コードの視認性が向上し、マニュアルの更新も Markdown 側を編集するだけで済むため、高度なナレッジ管理が可能になります。

SKILL.md とは？ファイル仕様と書き方の基本

Antigravity SDK において、エージェントに読み込ませる専門スキルの実体となるのが SKILL.md です。

SDK は指定されたディレクトリ配下のサブフォルダを探索し、「SKILL.md」という固定ファイル名を持つ Markdown ファイルを自動的に検知して「スキル」としてロードします（※ファイル名が異なると認識されないため注意が必要です）。

SKILL.md の具体的な記述例

---
name: customer-support-policy
description: ECサイトの注文キャンセル、返金、返品ポリシーに関する質問に回答するための専門スキル
---

# ECサイト カスタマーサポート対応規定

顧客からのキャンセル・返品・返金に関する問い合わせには、以下の規定に基づいて回答してください。

## 1. 注文キャンセル規定
- **発送前**: 注文後24時間以内かつ発送準備前であれば、無償でキャンセル可能です。
- **発送後**: お客様都合による発送後のキャンセルは不可となります（到着後の返品手続きを案内してください）。

## 2. 返品・返金規定
- **不良品・誤配送**: 商品到着後7日以内にご連絡いただいた場合、往復送料弊社負担にて交換または全額返金いたします。
- **お客様都合**: 未開封・未使用に限り、商品到着後7日以内のご連絡で返品可能です。ただし、返送時の送料はお客様負担となります。

## 3. 回答時のトーン＆マナー
- 常にお客様に寄り添い、丁寧で礼儀正しい敬語（です・ます調）で回答してください。

YAML フロントマター（メタデータ部分）の役割

  • name：スキルの識別ID（例: customer-support-policy）です。小文字英数字とハイフンで記述するのが一般的です。
  • description：スキル自動選択の「取説（インデックス）」となる説明文。AIエージェントはこの記述を読み取り、「ユーザーの質問に回答するために、この SKILL.md を発動すべきかどうか」を動的に判定します。「何の質問に答えるためのスキルなのか」を簡潔かつ具体的に記述するのがポイントです。

プロンプト本文（Markdown部分）の役割

スキルが選択された際に、AIエージェントが実際に参照する業務マニュアルや行動指針です。見出し（H1, H2）や箇条書きを用いて論理的に整理して記述することで、AIの読解・生成精度が向上します。

skills_paths を使用したサンプルPythonコード（skills_path_demo.py）

作成した SKILL.md が入ったディレクトリ（./skills）を LocalAgentConfig にセットしてエージェントを実行するサンプルプログラムです。

import asyncio
import os
from dotenv import load_dotenv
from google.antigravity import Agent, LocalAgentConfig

# 1. .env ファイルから環境変数をロード
load_dotenv()

async def main():
    # 2. 外部スキル（SKILL.md）が格納されているディレクトリを指定
    # LocalAgentConfig の skills_paths パラメータにフォルダパスを渡す
    config = LocalAgentConfig(
        model="gemini-3.1-flash-lite",
        system_instructions=(
            "あなたはECサイトのCS担当AIアシスタントです。"
            "必ず登録された専門スキル（SKILL.md）に記載されている事実のみに基づいて回答してください。"
            "SKILL.mdに書かれていない情報（マイページでの操作手順や、クレジットカード等の決済方法ごとの返金手順など）を推測で補足したり、回答に含めたりしてはなりません。"
        ),
        skills_paths=["./skills"]  # スキル定義（SKILL.md）が配置されたディレクトリパスを指定
    )

    user_query = "商品を購入したのですが、発送前ならキャンセルできますか？返金条件も教えてください。"

    print(f"ユーザーからの質問: {user_query}\n")
    print("--- [AIエージェントが SKILL.md を参照して回答生成中...] ---\n")

    # 3. Agent の非同期制御 (async with & await)
    async with Agent(config) as agent:
        response = await agent.chat(user_query)
        
        # 4. レスポンスのリアルタイム出力
        async for chunk in response.chunks:
            if hasattr(chunk, 'text') and chunk.text != "Finished":
                print(chunk.text, end="", flush=True)
        print("\n")

if __name__ == "__main__":
    asyncio.run(main())

プログラムの実行手順と動作確認

1. ディレクトリ構造の準備

以下のように、スクリプトと同階層に skills/customer-support/SKILL.md という命名ルールに従って配置を作成します。

project/
├── .env
├── skills_path_demo.py
└── skills/
    └── customer-support/
        └── SKILL.md

2. スクリプトの実行

python3 skills_path_demo.py

3. 実行結果の確認

ユーザーからの質問: 商品を購入したのですが、発送前ならキャンセルできますか？返金条件も教えてください。

--- [AIエージェントがスキルを参照して回答生成中...] ---

お問い合わせありがとうございます。注文のキャンセルおよび返金条件についてご案内いたします。

注文のキャンセルについては、**注文後24時間以内かつ発送準備前**であれば、無償でキャンセルを承っております。

ただし、返金条件は状況により異なります。恐れ入りますが、以下の規定をご確認いただけますでしょうか。

*   **不良品・誤配送の場合**: 商品到着後7日以内にご連絡いただいた場合、往復送料は弊社負担にて交換または全額返金いたします。
*   **お客様都合の場合**: 未開封・未使用に限り、商品到着後7日以内のご連絡で返品が可能です。なお、その際の返送送料はお客様負担となりますのであらかじめご了承ください。

上記規定に該当するかご確認いただき、お手数ですが改めてご連絡いただけますと幸いです。何卒よろしくお願い申し上げます。

このように、system_instructions にキャンセル規定を一切書かなくても、エージェントが自律的に SKILL.md 内の規定（24時間以内、7日以内、送料負担条件など）を読み取り、回答を生成してくれます！

プログラムコードの詳細解説

① SKILL.md によるメタデータと指示文の自動検索

SKILL.md の冒頭にある YAML フロントマター（description）は、エージェントが該当スキルを選択するための「インデックス（索引）」として機能します。エージェントはユーザーの質問（「発送前キャンセル」「返金条件」）をトリガーとし、最も合致する `customer-support-policy` スキルの本文を自動で参照して回答を組み立てます。

② LocalAgentConfig(skills_paths=[“./skills”]) による自動スキャン

skills_paths にフォルダリスト（[“./skills”]）を渡すことで、Antigravity SDK は配下のサブフォルダ内にあるすべての `SKILL.md` を自動的に探索して読み込みます。複数の専門スキル（例: 配送追跡スキル、領収書発行スキルなど）をフォルダごとに分けて配置するだけで、簡単に複数スキルの拡張が可能です。

skills_paths および SKILL.md 利用時の注意点

skills_paths と SKILL.md を利用する際の開発上の主な注意点です。

  • ファイル名「SKILL.md」のスペル厳守
    ファイル名が skill.md（小文字）や rules.md などになっていると、SDKが自動検知できず読み込み漏れが発生します。大文字で SKILL.md と正しく命名して作成することが求められます。
  • description の記述不足によるスキル未発動
    SKILL.md の `description`（説明文）が短すぎたり内容が曖昧だったりすると、AIエージェントが「どの質問の時にこのスキルを使うべきか」を判定できず、スキルが読み込まれない原因となります。想定されるユースケースを具体的に記述することが推奨されます。
  • パスの指定ミス（相対パス vs 絶対パス）
    スクリプトを実行するカレントディレクトリの位置によっては、`./skills` などの相対パスが見つからずにエラーや読み込み漏れが発生する場合があります。確実性を高めるためには os.path.dirname(__file__) 等を用いて絶対パスを生成して渡すのが安全です。

まとめ

今回は、Google Antigravity SDK の skills_paths と SKILL.md を活用し、AIエージェントに専門知識や指示書をモジュール化してスマートに読み込ませる手法について解説しました。

プロンプトを長文のまま直書きするのではなく、SKILL.md としてスキルごとに分割管理することで、保守性・拡張性に優れた実践的なAIエージェントシステムを構築できます！

コメント

タイトルとURLをコピーしました