Antigravity カスタムエージェントチュートリアル：専用スペシャリストを作る
繰り返す仕事を保存可能なサブエージェントに：.agents/agents の下に YAML フロントマター付き Markdown を 1 ファイル、限定されたツールリスト、さらにルール・ワークフロー・スキルを重ねる — スクリーンショットはすべて実録から。
要点まとめ
- カスタムエージェントは 1 枚の Markdown ファイル：YAML フロントマター（name、description、model、tools）にシステムプロンプト本文 — 繰り返すスペシャリストを一度保存すれば、毎セッションの説明は不要。
- ワークスペースのエージェントは .agents/agents/<name>.md に置いてリポジトリと一緒に配布；個人用は ~/.gemini/config/agents/ でマシン上の全プロジェクトに適用。
- tools は Antigravity の実在ツール名のみ（view_file、grep_search、list_dir）— 誤名は起動時に失敗；subagent: true で委譲可能になり、mainAgent: true で入力ピッカーに現れる。
- IDE ピッカーで "What are your tools?" と聞いてスモークテスト、メインチャットから委譲、CLI では /agents と Alt+J で確認 — その後ルール・ワークフロー・スキルを重ねる。
Google Antigravity Livestream: Remote Control and Custom Agents
チャンネル:Google Antigravity47:43
Antigravity Customization Features That 10X Your Coding Speed
チャンネル:Code A Program11:02
Defining Custom Subagents (.md) — Antigravity Docs
公式ドキュメント:antigravity.googleDocs
スクリーンショットは Code A Program の画面収録からのスチール（上記でクレジット）；カスタムエージェントファイルの手順自体は Google 公式ライブ配信と Antigravity の subagents ドキュメントに基づき整理 — 第三者のクリーンな収録はまだ存在しません。
事実確認には Use AI with Tech Dad と AI with Surya のカスタムエージェント解説も参照しました。商標はすべて Google に帰属します。本チュートリアルは独立したもので、Google とは提携していません。
空のフォルダから信頼できるスペシャリストへ
1 · スペシャリストの範囲を決める
- 1
保存する価値のある役割を見つける
同じ仕事が繰り返されるならカスタムエージェントのファイルを作る価値があります：固定チェックリストを持つコードレビュアー、依存関係の更新係、テスト実行係、ドキュメント整備係。指示が安定していて、汎用アシスタントと明確に違い、ツールボックスを事前に列挙できるなら保存しましょう。単発の依頼は通常のプロンプトで十分です。
- 2
サブエージェントやスキルとの違いを理解する
サブエージェントは「働き手の座」：メインエージェントが委譲するセッションです。カスタムエージェントはその座に就ける保存済みプロフィールで、直接対話もできます。スキルはまた別層：どんなエージェントでも拾えるタスク知識をパッケージ化するのに対し、カスタムエージェントは中核の指示とツールアクセスを変えます。単発の作業にファイルは不要。Antigravity はセッション中に define_subagent ツールで一時サブエージェントを生成できます。
- 3
スコープを選ぶ：リポジトリかマシンか
Antigravity は 3 か所でカスタムエージェントの .md を発見します。ワークスペース設定は .agents/agents/<name>.md（または .agents/agents/<name>/agent.md）に置き、リポジトリと共に配布 — チーム共有の規約に最適。グローバル設定は ~/.gemini/config/agents/<name>.md に置くとマシン上の全プロジェクトに適用 — 個人用スペシャリストに最適。プラグインは plugins/<plugin_name>/agents/ にエージェントを同梱できます。
Antigravity ドキュメントの Rules ページ：グローバルルールは ~/.gemini/GEMINI.md に置かれ全ワークスペースに適用、ワークスペースルールは .agents フォルダに — カスタムエージェントファイルも同じ区分けに従います。動画 0:30 付近
2 · エージェントファイルを書く
- 4
エージェントファイルを作成する
プロジェクト内でフォルダとファイルを一度に作成 — ファイル名やフォルダ名がエージェントの識別子になるため、小文字とハイフンで：.agents/agents/codereviewer/agent.md。Antigravity エージェントに作らせることも可能：公式ウォークスルーでは "I have an idea for a custom agent" の一文で、完全パス undefined/.agents/agents/codereviewer/agent.md と編集可能な定義が返ってきました。
- 5
YAML フロントマターを書く
フロントマターはスペシャリストの正体と境界を宣言します。name は一意に — メンションはこの名前で。description は Antigravity に「いつ呼ぶか」を伝える求人広告のように書きます。model: inherit は親のモデル階層を引き継ぎ、tools は役割が使えるものを正確に列挙。さらに 2 つのフラグ：subagent はデフォルト true（委譲可能）、mainAgent はデフォルト false（true にすると入力ピッカーから直接選択可能）。
- 6
システムプロンプト本文を書く
フロントマター区切り以下のすべてがエージェントのシステム指示になります。公式サンプルはペルソナで始まり（"You are an expert, meticulous Code Reviewer"）、核心の責務 — 正確性、セキュリティ、パフォーマンス、スタイル — を列挙し、厳格な出力フォーマットで締めます：Summary の判定、行参照付きのブロッキングな Critical findings、非ブロッキングな Suggestions。安定した報告フォーマットこそが結果の信頼性を作ります。
---
name: codereviewer
description: >-
Code review specialist that analyzes diffs, inspects code for bugs,
architectural issues, performance bottlenecks, and style compliance.
model: inherit
tools:
- view_file
- grep_search
- list_dir
subagent: true
---
# Code Reviewer Persona & Instructions
You are an expert, meticulous Code Reviewer. Inspect proposed changes,
pull requests, and codebase files for correctness, security, performance,
and style.
## Review Output Format
- **Summary**: high-level assessment (LGTM / Changes Requested)
- **Critical findings**: blocking issues with line references and fixes
- **Suggestions & Improvements**: non-blocking refactors3 · 拡張と制約を加える
- 7
実在ツール名でツールボックスを制限する
tools フロントマターは明示的な許可リストを取り、名前は Antigravity の実在ツールと一致しなければなりません。公式ウォークスルーでは生成ファイルに read と書かれ、"Agent execution terminated due to error" で即死 — view_file に修正されて復活しました。view_file、grep_search、list_dir など実在名に絞り、役割に必要な最小限だけ与えます。レビュアーに書き込み権はほぼ不要です。
エージェントが呼び出せるツール名を列挙したワークスペース設定ファイル — view_file、grep_search、read_file — カスタムエージェントの tools リストが期待する語彙そのものです。動画 4:44 付近 - 8
いつ働くかを決める
subagent: true（デフォルト）ならスペシャリストは委譲可能：メインエージェントに仕事を説明すると、境界づけられたタスクがスペシャリストに渡り、報告がメイン会話に戻ります。委譲されたサブエージェントは親の権限境界を継承 — コマンド許可、ファイルスコープ、サンドボックス設定 — 承認が必要な操作はメイン UI に現れます。さらに mainAgent を true にすると入力ピッカーにも現れ、直接対話できます。
- 9
Customizations を開いてルールを命名する
ハウスルールを足すとカスタムエージェントは一気に賢くなります。IDE でエージェントペイン上部の「...」ドロップダウンから Customizations を開く — Rules と Workflows は同じパネルにあります。Rules の下で新規ルールを作成：グローバルルールは ~/.gemini/GEMINI.md に置かれ全ワークスペースに適用、ワークスペースルールはワークスペースまたは git ルートの .agents フォルダに。ルールファイルは 12,000 文字まで。
Antigravity のエージェントペインにある Customizations パネル：Rules タブがアクティブで、新規ルール名を入力中。プレースホルダーは e.g. code-style-guide。動画 0:56 付近 - 10
発動モードを選ぶ
すべてのルールは一つの問いに答えます：いつ適用するか？Always On はすべての会話に注入され、Manual は入力欄での @メンションを待ち、Model Decision は自然言語の説明をもとにエージェントが判断し、Glob は *.test.ts のようなパターンに合うファイルだけに適用されます。効く最も狭いモードを選びましょう — diff でのみ発動するレビュアルールは集中を保てます。
Antigravity のルールエディタにある Activation Mode ドロップダウン、4 つの選択肢が全表示 — Always On、Manual、Model Decision、Glob。動画 1:04 付近 - 11
ルールの内容を書く
ルールは素の Markdown の制約です：「コメントは何をしているかではなく、なぜそう書くかを説明する」「関数には JSDoc を」「TODO を残さない」。1 ルール 1 目的 — エージェントは該当する会話ごとに文字どおり読み込みます。ルールはスペシャリストの働き方を形作り、次の 2 層が手順と知識を与えます。
Antigravity エディタの comments.md ルールファイル、Activation Mode は Always On、毎会話で従う Markdown 指示を書き込む状態。動画 1:02 付近 - 12
繰り返す手順をワークフローにまとめる
スペシャリストが複数ステップの手順を繰り返すなら — マージ済みブランチの掃除、リリース作成、API ドキュメント再生成 — 手順を書き直す代わりにワークフローとして保存します。ワークフローはフロントマターに YAML の description を持つ Markdown ファイルで、スラッシュコマンドで発動：/cleanup-branches と入力すれば、エージェントが列挙された各ステップを実行します。
Antigravity ドキュメントの Workflows セクション：ワークフローファイルは .agent の workflows フォルダに置き、スラッシュコマンドで呼び出します。動画 5:40 付近 - 13
ワークフローファイルを作る
エージェントに足場を作らせるか、自分で：mkdir -p .agent/workflows の後、短い description フロントマターと番号付きステップリストを備えた cleanup-branches.md を作成。録画された例ではステップは git fetch --prune からマージ済みブランチの削除まで — 各ステップが明示されているからこそ、破壊的操作の前でエージェントは止まって尋ねます。
Antigravity の会話：エージェントが mkdir -p .agent/workflows と nano を実行し、保存すべきワークフロー Markdown — description フロントマターと 10 ステップの git クリーンアップ Checklist — を受け取る場面。動画 6:20 付近
4 · テストと導入、レイヤーの整理
- 14
ガードレールの実動を見る
録画されたワークフロー実行は、エージェントがフェッチしたブランチを報告し、feature/about-page はマージ済みで削除しても安全だと判断し、何かに手を触れる前に "Would you like me to proceed with deleting these?" と尋ねる場面で終わります。この承認の習慣は委譲されたカスタムエージェントにも及びます：ユーザー認可が必要な操作はメイン UI に現れ、スペシャリストが黙って境界を越えることはありません。
エージェントのワークフロー報告：feature/about-page はマージ済みで削除安全、git branch -d と git gc の前に "Would you like me to proceed?" と確認。動画 7:46 付近 - 15
スキルを教える
ルールは振る舞いを、スキルは知識を加えます。スキルは SKILL.md を含むフォルダ — ワークスペース用は .agents/skills/<skill-name>/、個人用は ~/.gemini/skills。フロントマターの name と description がどんなとき役に立つかをエージェントに伝え、本文が完全な指示・スクリプト・参照を担います。カスタムエージェントとスキルは組み合わせ可能：codereviewer に nextjs-reviewer スキルを持たせフレームワーク固有のチェックを補わせられます。
Antigravity ドキュメントの Agent Skills セクション：スキルディレクトリのいずれかにフォルダを作り、YAML フロントマター付きの SKILL.md を追加する手順。動画 8:42 付近 - 16
SKILL.md のフロントマターを書く
description はトリガーのように書きます："Reviews Next.js and TypeScript code for critical issues only — types, performance, security, and App Router patterns"。リクエストが合えばエージェントはスキル全体を読み込み、合わなければスキルは邪魔をしません。この漸進的読み込みこそ、深いリファレンス資料をエージェントのシステムプロンプトではなくスキルに置く理由です。
Antigravity エディタの nextjs-reviewer SKILL.md：YAML フロントマターにスキル名と説明 — Reviews Next.js and TypeScript code for critical issues only。動画 9:16 付近 - 17
実レビューでスキルが発動するのを見る
録画セッションでは、Next.js コードのレビューを依頼するとエージェントはレビュアースキルを読み込み、ページを分析し、構造化されたレビューを返しました：Project Strengths では型付きユーティリティとフォント最適化が取り上げられ、編集前に "Would you like me to apply these fixes for you?" と確認。同じ出力フォーマットをプロンプトに求めれば、あなたのカスタムエージェントもこの規律を継承します。
レビュアーエージェントの実働：プロジェクトの強み — 型付きユーティリティ、next/image、App Router パターン — を列挙し、修正を適用するか尋ねます。動画 10:15 付近 - 18
IDE と CLI の両方でテストする
mainAgent: true にするとスペシャリストが入力ピッカーに現れます — 選んで "What are your tools?" と聞けばツールボックスの配線を確認できます；壊れた tools リストは即座に実行エラーで失敗し、それが最速のスモークテストです。CLI では /agents コマンドが発見済みエージェントを一覧し、Alt+J でサブエージェントパネルが開き、委譲作業をリアルタイムで追えます。
- 19
フォルダをコミットしてチーム全員が同じスペシャリストを使えるように
スペシャリストに必要なものはすべてリポジトリに揃いました：エージェント定義は .agents/agents/、さらに rules・skills・workflows を含む .agent フォルダがソースの隣に。コミットすれば、すべてのチームメイトとすべての CI 実行が、同じ境界を持つ同じスペシャリストを発見します。~/.gemini の個人設定はリポジトリに入れません — マシン全体の好みです。
Antigravity のエクスプローラーで展開した .agent フォルダ — agent、rules、skills、workflows がアプリのソースの隣に並び、コミット可能な状態。動画 9:04 付近 - 20
どのレイヤーが何をするかを把握する
3 つのカスタマイズ層はエージェントファイルを置き換えるのではなく補完します：Rules は常にオン（またはパターン発動）のコーディング標準、Workflows はスラッシュコマンドの手順、Skills は自動発見される専門知識。カスタムエージェントはそれらを結ぶアイデンティティ — 繰り返す仕事に名前とツールボックスと記憶を与える 1 枚の Markdown ファイルです。
Rules vs Workflows vs Skills の比較表：コーディング標準は自動適用、タスク自動化はスラッシュコマンド、専門知識は必要時に自動発見。動画 10:20 付近