Antigravityとほかのツール・AIをつなぐ手順（その2）：ルール、スキル、フック、サブエージェント、サイドカー、SDK、ヘッドレス実行と、ほかのAIとの組み合わせ方・権限・外し方

この記事は、公式の資料を2026年10月25日に読んでまとめたものです。この記事は、実際に使って確かめた記録ではありません。運営者はAntigravityを入れていますが、使い心地はこの記事には書いていません。手順は「公式の手順を順に並べたもの」で、設定の例は、公式ページが載せていたものを要約の形で読んだ範囲で写しています。「この記事の案」と書いた部分は、公式の記載に合わせて組んだ案で、動作は確かめていません。画面の表記は版で変わるので、手元の画面と照らして読んでください。

先に結論

• 「何を、どこに置くか」の早見：

• ルールは「常に効く決まり」、スキルは「必要なときに読む手順」です。 公式のRulesページは、制約や不変の決まりにはルール、複数の手順の作業にはスキルを使う、という趣旨で書いています。
• 自分のプログラムから使う入口は2つあります。 Python の SDK と、CLI の agy -p（ヘッドレス）です。どちらも、承認を求められない場面での権限の決め方が、設計の中心です。

前提：用語をそろえる

• ルール：エージェントの文脈に常に（または条件つきで）入る、永続の指示です。コーディングの規約や構造の制約などです。
• スキル：SKILL.md に手順を書いたフォルダです。エージェントは、会話の始めに名前と説明だけを見て、関係がありそうなときに全文を読みます（公式の「progressive disclosure」）。
• ワークフロー：手順を書いた Markdown のファイルで、/ワークフロー名 で呼びます。公式は、これを新しい仕組みに置き換える予定と書いています。
• フック：エージェントの動きの途中で、自分のスクリプトを動かす仕組みです。
• サブエージェント：メインのエージェントが背景で動かす、別の役割のエージェントです。
• サイドカー：Antigravity が起動して見守り、止まったら再起動してくれる、背景のプロセスです。
• SDK：プログラムの中で、ある道具を使うための部品の集まりです。Antigravity SDK は Python のパッケージ google-antigravity です。
• ヘッドレス（print mode）：画面なしで、1回だけ指示を送って答えを受け取り、終わる使い方です。

つなぎ方1：ルールを書く（AGENTS.md、GEMINI.md、rules）

置き場所

公式のRulesページの内容です。

• 作業フォルダごと：Antigravity は、読んだり編集したりするファイルのフォルダから、ワークスペースのルートまでさかのぼり、各階層で次を読み込みます。AGENTS.md か GEMINI.md、.agents/AGENTS.md か .agents/GEMINI.md、.agents/rules/*.md（以前の .agent/rules/*.md も使える）。.agents/rules/ の中は、直下の .md ファイルだけが対象で、入れ子のフォルダは、.agents/rules.json に登録しないと無視されます。
• 全体：~/.gemini/AGENTS.md、~/.gemini/GEMINI.md、~/.gemini/config/AGENTS.md、~/.gemini/config/GEMINI.md（frontmatter なし、常に有効）。~/.gemini/config/rules/*.md（frontmatter が必須）。CLI だけ、~/.gemini/antigravity-cli/rules/*.md とプラグインのルール。
• 複数の範囲のルールは合わせて使われ、衝突したときは、より具体的なフォルダのルールが優先される、と書かれています。

書き方

AGENTS.md と GEMINI.md は、frontmatter なしの普通の Markdown で、そのフォルダの範囲では常に有効です。rules/ の中のファイルは、先頭に YAML の frontmatter が必要です。

公式の例は次の形です。

---
trigger: glob
globs: "*.proto, **/*.pb.go"
description: "Protobuf schema design and backward-compatibility rules."
---

つまずきやすい点（公式の注意）：frontmatter がないファイルや、alwaysOn、modelDecision のような認識されない trigger のファイルは、黙って捨てられます。

制限：1ファイル24,000バイト（@[label](path) の展開後で測り、超えると切り捨て）。全体のルールと always_on のルールは、合わせて20,000トークンの枠を共有し、超えると、大きなファイルから「- <path>: <description>」の形の案内に縮められ、エージェントが必要なときに読みます。

UI で作る

• App：アプリケーションのメニューかプロジェクトの設定から Customizations のパネルを開き、Rules のタブで + Global か + Workspace を押す。
• IDE と拡張機能：エージェントのパネルの上の「…」→ Customizations → Rules → + Global／+ Workspace。
• CLI：ファイルの置き場所は書かれていますが、UI での作り方は書かれていません。

外し方

ルールのファイルを消すか、trigger を manual にする、というのが、公式の記載から組める外し方です。ファイルの外し方そのものを、公式が説明している箇所は見つかりませんでした。

会話から作る（/learn）

/learn は、会話の中の訂正や失敗の直し方から、ルールかスキルとして残す案を作ります。公式の流れは次です。

1. /learn と打つ（または /learn <残したいこと>）。
2. エージェントが既存のファイルを調べ、learning_proposal.md の成果物を作る。分類（ルールかスキル）、理由、変更の予定が書かれる。
3. インラインのコメントで、範囲や書き方を直す。
4. あなたが承認してから、ファイルが変わる。公式は、設定ファイルをすぐには編集しないと書いています。

保存先は、ルールが AGENTS.md／GEMINI.md か .agents/rules/<名前>.md、スキルが .agents/skills/<名前>/SKILL.md（全体は ~/.gemini/config/ の下）です。

つなぎ方2：スキルを足す

置き場所と書き方

公式のSkillsページによると、スキルは、SKILL.md が必須のフォルダです。scripts/、examples/、resources/ は任意です。

.agent/skills（単数）も、後方互換で使える、と書かれています。SKILL.md の先頭の frontmatter は、name（任意、小文字とハイフン。省略するとフォルダ名）と description（必須。何をするか、いつ使うか）です。公式の例の要旨は次のとおりです。

---
name: code-review
description: Reviews code changes for bugs, style issues, and best practices. Use when reviewing pull requests or checking code quality.
---

# Code Review Skill
（本文：手順や確認の項目を書く）

呼ぶ方法

• 自動：エージェントが説明を見て、関係がありそうなときに読む。名前を言って指定することもできる。
• 手動（App）：入力欄に /<skill-name> と打つ。
• 手動（CLI）：スキルを定義すると、同じ名前のスラッシュコマンドができる（例：deploy-staging なら /deploy-staging）。/skills で、読み込まれたスキルを見る。
• IDE：エージェントのパネルの Customizations で、有効なスキルを見る。

プラグインやリポジトリから入れる

agy plugin list
agy plugin install <plugin-name>
agy plugin install https://github.com/<owner>/<repo>
agy plugin install ./my-skills-plugin

公式は、ワークスペースのスキルをバージョン管理に入れてチームで共有する使い方を書いています。

ワークフロー（IDE）とスキルへの移行

公式のIDE Workflowsのページは、ワークフローを、手順を書いた Markdown のファイルで、IDE の Customizations → Workflows で + Global か + Workspace を押して作り、/ワークフロー名 で呼ぶ、と書いています（1ファイル12,000文字まで）。同じページと移行のページは、「現在のワークフローは2026年10月19日に動かなくなる」と書いています。2026年10月25日の今日は、その日付を過ぎていますが、実際に止まったかどうかは、読んだ範囲では確認できていません。

移行のページの手順は次です。

ファイルの場所の対応は、作業フォルダが .agents/workflows/<name>.md から .agents/skills/<name>/SKILL.md、全体が ~/.gemini/config/workflows/<name>.md から ~/.gemini/config/skills/<name>/SKILL.md です。同じ名前なら、スキルが優先される、と書かれています。

つなぎ方3：サブエージェントを定義する

公式のSubagentsページの内容です。

置き場所と書式

Markdown のファイルで、先頭の YAML に、name（必須）、description（必須。計画役が、いつ任せるかを決める材料）、tools（許可する道具の明示の一覧）、mainAgent、subagent、model（inherit、flash、pro）、commandExecutionPolicy（off、auto、eager、sandbox。既定は sandbox）、mcpServers、skills／plugins を書きます。本文がシステムプロンプトです。公式の例の要旨は次のとおりです（途中は省略されています）。

---
name: code-auditor
description: Specialized subagent for security audits, static analysis, and code quality reviews.
tools:
  - view_file
  - grep_search
  - run_command
subagent: true
mainAgent: false
model: pro
commandExecutionPolicy: sandbox
---

つまずきやすい点（公式の既知の問題）：tools に、対応していない、またはつづりの違う道具の名前を書くと、サブエージェントが止まることがあります。検証と修正は予定、と書かれています。

動き

• 親のエージェントが invoke_subagent で、役割と最初の指示を渡す。サブエージェントは親の会話の履歴を引き継がず、新しく始まる。
• 作業場所の指定は3つで、inherit（親と同じ）、branch（独立した Git の worktree）、share（ディレクトリの保存を共有）。
• 公式が最初から用意するサブエージェントは、research（調査）、browser（/browser のときだけ）、self（自分の複製）。
• 進み具合は、App ではサブエージェントのパネル、CLI では Alt+J か /agents。承認の待ちは、CLI で Alt+J（次の待ちへ）と Ctrl+K（今の会話を離れずに承認）で扱えます。
• 状態は Running、Idle、Killed。入れ子は10段まで。変更履歴は、サブエージェントに直接メッセージを送れる（v2.19.1）と書きます。

権限

commandExecutionPolicy と tools が、そのサブエージェントの権限を決めます。CLI の accept-edits モードでは、サブエージェントも同じ設定を引き継ぐ、と CLI の Modes ページは書いています。外し方は、定義のファイルを消すことですが、公式がこの手順を説明している箇所は見つかりませんでした。

つなぎ方4：フックでスクリプトをはさむ

公式のHooksページの内容です。シェルのコマンドを動かす仕組みなので、書いた内容がそのまま権限になります。

置き場所

• App：作業フォルダの .agents/hooks.json、または全体の ~/.gemini/config/hooks.json。Settings → Customizations → Hooks で切り替えられる。
• CLI：同じ2つに加え、入れたプラグインの hooks.json。~/.gemini/antigravity-cli/settings.json の中のフックは読み込まれない。/hooks で、有効なフックを見る。
• IDE：同じ2つ。エージェントのパネルの「…」→ Customizations → Hooks。

書式の要点

• ファイルは、フックの名前をキーにして、イベントごとの設定を持つ。各フックに enabled（既定は true）。
• 各ハンドラは type（"command" のみ）、command（必須）、timeout（秒。既定30）。
• PreToolUse と PostToolUse は matcher（道具の名前への正規表現。"" か "*" ですべて）。ほかのイベントは、ハンドラの一覧だけ。

フックは標準入力で JSON を受け取り、標準出力で JSON を返します（項目名は camelCase）。PreToolUse の返事の decision は必須で、allow、auto_approve、deny、ask、force_ask、deny_unless_prior_grant のどれかです。deny はすぐに実行をふさぎ、ask は「Always Allow」の設定を尊重し、force_ask はそれを無視します。overwrite は、道具の引数を書き換え、書き換えたキーを知らせる注意書きが結果の前に付きます。

Stop のフックの出力の公式の例は次です（Stop は、実行のループが終わるときに動き、continue で止まるのを防いでループに戻る、という説明です）。

{ "decision": "continue", "reason": "Not done yet" }

"continue" を返すと、ループに戻ります。常に continue を返すフックが動き続けるかどうかについて、公式の Hooks ページに注意書きは見つかりませんでした（動き続けてしまうのではないか、というのは僕らの見立てです）。

外し方と確認点

• 外す：enabled を false にする、ファイルを消す、App の Hooks の画面で切り替える。
• 確認：CLI は /hooks。
• 公式のページは、終了コードの扱いを書いていません。

つなぎ方5：サイドカーで背景の仕事を動かす

公式のSidecarsページの内容です。

• 置き場所：全体は ~/.gemini/config/sidecars/<sidecar-dir>/sidecar.json、プラグインは ~/.gemini/config/plugins/<pluginName>/sidecars/<sidecar-dir>/sidecar.json。実行時のデータは ~/.gemini/antigravity/sidecar_data/<sidecarId>/ の data/、logs/、events/。
• 既定は無効です。~/.gemini/config/config.json で有効にします。
• sidecar.json の項目：command か builtin（現在は schedule のみ）のどちらか、args、restart_policy（always、on-failure、never。既定は always）、description、env、display_name。

有効にする config.json の公式の例は次です。

{
  "sidecars": {
    "my-worker": { "enabled": true }
  }
}

schedule の組み込みで会話を作る sidecar.json の、この記事で組んだ例です（公式の構造に合わせたもので、動作は確かめていません）。公式のページの例は、毎時（0 * * * *）に、受け取ったレビュー依頼の要約を頼む内容で、args の最初が5項目の cron 式、続きがコマンドとその引数、という並びです。下の例は、その並びに合わせて、平日の9時30分にしたものです。

{
  "description": "Morning digest",
  "builtin": "schedule",
  "args": ["30 9 * * 1-5", "agentapi", "new-conversation", "Summarize overnight alerts."]
}

サイドカーからは agentapi コマンドが使えます。agentapi new-conversation <prompt>（projectId が必要）と agentapi send-message <conversation_id> <prompt> です。外すには、enabled を外すか、sidecar.json のフォルダを消します（消す手順の記載は見つかりませんでした）。

つなぎ方6：Python の SDK から使う

公式のSDKのページとGitHubのリポジトリ（google-antigravity/antigravity-sdk-python、Apache License 2.0）の内容です。

基本

pip install google-antigravity
export GEMINI_API_KEY="your_api_key_here"

公式のクイックスタートの要旨は、LocalAgentConfig() を作り、Agent(config) を非同期のコンテキストマネージャとして開き、agent.chat(...) で聞いて await response.text() で受け取る、というものです。実行の本体（バイナリ）は PyPI の配布物に入っていて、リポジトリのコピーだけでは動かない、と注意書きがあります。

認証

• Gemini API：GEMINI_API_KEY、または LocalAgentConfig の api_key。
• Gemini Enterprise（Vertex）：vertex=True と project、location。または環境変数の GOOGLE_GENAI_USE_VERTEXAI、GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION。gcloud auth application-default login が要る。明示の引数が環境変数より優先される、と README は書いています。

権限（公式の設計の中心）

• 既定は読み取り専用です。書き込みの道具を含めて使うには、capabilities=CapabilitiesConfig() を渡します。
• 方針の関数：deny(...)、allow(...)、ask_user(...)。（enforce は、読んだ範囲の Policies ページと Tools ページに説明が見つからず、公式で確認できていません。）公式の Policies ページの例の要旨は次のとおりです。

policies = [
    deny("*"),                                     # Deny all tools by default
    allow("view_file"),                            # Allow file viewing
    ask_user("run_command", handler=my_handler),   # Ask approval for shell
]
config = LocalAgentConfig(policies=policies)

• 既定では、自分で書いた Python の関数と、標準の読み取り専用の道具は許可、run_command のような危険の高い操作は、明示の許可か方針のルールが要る、と書かれています。
• policy.safe_defaults(handler=...) は、読み取りの道具は許可し、書き込みの前に聞く方針です。実行時には Allow execution? (y/n) [n]: のような確認が出ます。
• CapabilitiesConfig の enabled_tools／disabled_tools で、使える道具を絞れます（例：enabled_tools=BuiltinTools.read_only()。Tools ページの記載）。

MCP、スキル、道具

• MCP は mcp_servers=[McpStdioServer(...)] などで渡す。例は name、command、args、env を持ちます。MCP の道具への方針の掛け方は、SDK の Policies ページにも MCP ページにも書かれていませんでした。
• スキルは skills_paths に、スキル1つのフォルダ、または複数のスキルを含む親のフォルダを渡す。
• 自作の Python の関数は tools=[...] に渡す（型ヒントと docstring が説明になる）。
• 組み込みの Web の道具 SEARCH_WEB（Google 検索）と READ_URL_CONTENT は、既定で有効、と書かれています。

ローカルのモデルにつなぐ

SDK は、キーなし・ネットなしで動かす2つの方法を持ちます。

ローカルのモデルを使うと、モデルの呼び出しは手元で動きます。そのほかのデータの扱いは、README には書かれていません。

渡るデータと外し方

モデルの呼び出しは、Gemini API か Gemini Enterprise の API（aiplatform.googleapis.com）に送られます。外し方は、コードから Agent の設定を消すことや、キーを環境変数から外すことですが、公式がこの手順を書いている箇所は見つかりませんでした。

つなぎ方7：ヘッドレス（agy -p）でスクリプトや CI から呼ぶ

公式のHeadlessページの内容です。05と06に書いた使い方の続きです。

1. 先に、対話で1回サインインしておく（キャッシュされた認証を使う）。
2. 使う：

agy -p "..." --output-format json

1. 結果の確認：json なら status、conversation_id、response などが返る。公式の CI の案内は、status が SUCCESS か確かめ、そうでなければジョブを失敗にし、jq で応答を取り出す、という流れです。
2. 続きの会話：--continue（-c）か --conversation <id>。
3. 構造化した出力：--json-schema（スキーマの文字列、.json のパス、または型の名前）。
4. 承認の扱い：承認が要る操作は拒否扱いで続く。事前に許可するなら settings.json の permissions.allow に command(git) のように書く。--dangerously-skip-permissions は全部を承認するもので、範囲を絞った許可ルールを使うように、という趣旨で書かれています。
5. --sandbox で、ターミナルのサンドボックスを有効にできる。

終了コードは、成功が0、失敗が0以外で、理由が標準エラー出力に出ます。待ち時間は既定で5分で、--print-timeout で変えられます。

認証の別の道として、Gemini API キー（modelProvider: "gemini" と GEMINI_API_KEY）や ADC（AGY_ADC_AUTH=true）は、05に書きました。

ほかのAIとの組み合わせ方：公式に書かれていること

第三者のソフトとの関係（公式のFAQ）

公式のFAQは、次のように書いています。

• 第三者のソフト、ツール、サービスを使って Antigravity にアクセスすることは、利用規約に反し、ほかの利用者の体験を損ない、アカウントの停止や終了につながることがある。
• 第三者のコーディングエージェントで Gemini を使いたい場合に、Googleが挙げるのは、Gemini Enterprise か Google AI Studio の API キー。
• ヘッドレス（agy -p）は、直接のスクリプトや CI のため。個人向けのプランでは、agy を第三者のエージェントやアプリで包むことと、アカウントを自動で切り替えて回すことは、対応しない。

今回読んだFAQの要約は、第三者のソフトの名前を挙げていませんでした。01・03では、FAQが具体的な名前を挙げていると整理しています。名前の一覧は、公式のFAQと利用規約で確かめてください。

この記事の案（公式の手順ではありません）

• 別のAIのコーディングツールと同じリポジトリで併用する場合、Antigravity が読む AGENTS.md に、共通の決まり（テストの実行のコマンドなど）を書いておくと、どのツールから見ても同じ前提が置ける、という案です。ほかのツールが AGENTS.md を読むかどうかは、この記事の公式資料の範囲では確認していません。
• Antigravity から、ほかのサービスの情報を使わせるときは、先に MCP のツール単位の許可（enabledTools／disabledTools、mcp(server/tool)）で、使わせる範囲を絞る、という案です。
• スクリプトに組み込むときは、書き込みの許可を、最初は allow の絞った一覧にして、--dangerously-skip-permissions は使わず、足りないものを1つずつ足す、という案です。

権限と外し方のまとめ

気をつけること

• この記事は、実際に使って確かめた記録ではありません。運営者はAntigravityを入れていますが、使い心地はこの記事には書いていません。
• ワークフローは、公式のページが2026年10月19日に動かなくなると書いていた機能です。読んだ日は、その日付のあとです。今も動くかは確認できていません。スキルへの移行の案内に従ってください。
• フック、サイドカー、プラグインの中のスクリプトは、あなたのパソコンでコマンドを動かします。書いてある内容を、入れる前に読んでください（僕らの見立て）。Stop のフックが continue を返し続ける場合の動きは、公式の Hooks ページには注意書きが見つかりませんでした。
• 公式のページ同士で書き方が違う所があります。CLI のコマンド一覧のページと Custom subagents のページは /agents を「Agent Manager」のパネルを開くコマンドと書く一方、CLI の機能のページは、同じ /agents を「サブエージェントのパネル」を開くコマンドとして説明しています。概要のページは、App は Agent Manager から発展した、と書きます。変更履歴には Agent Manager は出てきません。
• 第三者のソフトから Antigravity にアクセスすることについて、公式のFAQは、規約に反し、アカウントの停止や終了につながることがあると書いています。
• 規約やデータの解釈は、必要なら公式や専門家に確認してください。この記事は法律の助言ではありません。

出典

• Rules（Google Antigravity Docs、確認日 2026-10-25）
• Skills（Google Antigravity Docs、確認日 2026-10-25）
• IDE Workflows（Google Antigravity Docs、確認日 2026-10-25）
• Workflows to Skills（Google Antigravity Docs、確認日 2026-10-25）
• /learn（Google Antigravity Docs、確認日 2026-10-25）
• Custom subagents（Google Antigravity Docs、確認日 2026-10-25）
• Lifecycle hooks（Google Antigravity Docs、確認日 2026-10-25）
• Sidecars（Google Antigravity Docs、確認日 2026-10-25）
• Antigravity SDK overview（Google Antigravity Docs、確認日 2026-10-25）
• SDK Policies（Google Antigravity Docs、確認日 2026-10-25）
• SDK MCP（Google Antigravity Docs、確認日 2026-10-25）
• SDK Tools and skills（Google Antigravity Docs、確認日 2026-10-25）
• SDK Local models（Google Antigravity Docs、確認日 2026-10-25）
• antigravity-sdk-python（GitHub google-antigravity、確認日 2026-10-25）
• CLI headless mode（Google Antigravity Docs、確認日 2026-10-25）
• CLI execution modes（Google Antigravity Docs、確認日 2026-10-25）
• CLI commands reference（Google Antigravity Docs、確認日 2026-10-25）
• CLI features（Google Antigravity Docs、確認日 2026-10-25）
• Models（Google Antigravity Docs、確認日 2026-10-25）
• Gemini CLI migration（Google Antigravity Docs、確認日 2026-10-25）
• /boost（Google Antigravity Docs、確認日 2026-10-25）
• /teamwork-preview（Google Antigravity Docs、確認日 2026-10-25）
• FAQ（Google Antigravity Docs、確認日 2026-10-25）
• Changelog（Google Antigravity Docs、確認日 2026-10-25）