Antigravity Skillsの使い方｜業務手順を型化して再利用する設計ガイド

本記事を読めば、毎回10〜15分かかっていた定型プロンプト作成をほぼゼロに近づけ、チームのAI活用手順を再利用できるようになります。

AntigravityのSkillsは、業務手順や開発フローをエージェントに記憶させる機能です。AIzen株式会社は、AIを組み込んだ業務アプリ開発や開発フロー設計を支援する中で、AI活用の定着には「指示の再現性」が前提条件になることを実感してきました。

本記事では、Skillsの仕組みから粒度設計、作成手順、トラブル時の切り分け、チーム運用ルールまでを実装視点で解説します。

Antigravity Skillsとは

AntigravityのSkillsは、エージェントの動作を再利用可能な「手順書」として外部ファイルに切り出す仕組みです。一度型化しておけば、同じ指示を毎回プロンプトで書く必要がなくなり、業務の再現性を担保できます。

Skillsで解消できるプロンプトの書き直し負担

プロンプトを毎回ゼロから書く運用では、指示者によって品質が揺れ、過去の指示を探し回る無駄も発生します。Skillsは、こうした繰り返し作業をエージェントの中に固定化することで解決します。

たとえば、コードレビューの観点、テスト実行前の前準備、デプロイ手順といった「毎回同じことを伝えている指示」をSKILL.mdに書き出しておけば、トリガー条件に応じて自動で読み込まれます。

プロンプトに含める情報は実行ごとの差分だけでよくなり、書き直しの負担が大きく減ります。

業務手順をエージェントに記憶させる仕組み

Skillsは「ディレクトリ＋SKILL.mdファイル」の形で管理されます。SKILL.mdには、Skillsの名前、説明、発火条件、実際の手順などをMarkdownで書き、必要に応じて参照スクリプトやサンプルファイルを同じディレクトリに配置します。

Antigravityは、ユーザーの指示内容を解釈する際にまずSKILL.mdのメタデータ（名前と説明）だけを軽量に読み込み、関連性が高いと判断したSkillsのみを実際にコンテキストへ展開します。

常時ロードされるシステムプロンプトとは異なり、必要なときだけ呼ばれる構造のため、コンテキスト消費を抑えながら多数のSkillsを併存させられます。

Skillsで自動化できる範囲と人が確認すべき範囲

Skillsで自動化に向くのは、入力と出力の関係が安定している作業です。具体的には次のような領域が該当します。

• コードレビューやテスト実行の前準備など、決まった観点でのチェック作業
• ドキュメント生成、議事録整形、リリースノート起こしなど、テンプレートに沿った文書化
• 開発環境のセットアップ、依存関係の確認など、コマンド列が固定的な作業

一方で、要件の優先順位付けや顧客折衝の方針決定など、文脈判断が大きく入る作業は人がレビューを挟む前提でSkillsを設計するべきです。

Skillsは「型化できる作業を任せる」「型化しきれない判断を人に残す」という分担を最初に明確化すると、運用が崩れにくくなります。

Antigravity Skillsの粒度設計の決め方

Skillsをどの単位で切り出すかは、作成手順より先に決めるべき論点です。粒度を誤ると、せっかく作ったSkillsが呼び出されない、もしくは複数のSkillsが衝突するという状態になります。

業務単位・タスク単位・関数単位の使い分け

Skillsの粒度は大きく3つのレイヤーに分けて考えると整理しやすくなります。

粒度	想定される範囲	向く作業の例
業務単位	1つの業務プロセス全体	リリース作業一式、月次レポート生成
タスク単位	業務内の独立した工程	テスト実行、ドキュメント生成、PR作成
関数単位	単一の処理やチェック	命名規則チェック、特定ライブラリの使い方確認

業務単位は「リリース作業」のように複数工程を含むため、内部で複数のタスクや関数を呼び出す入れ子構造になりやすいです。タスク単位は単独で完結し、複数の業務から呼び出される共通部品として機能します。

関数単位は最も粒度が小さく、他のSkillsから内部的に参照される基礎部品の位置づけになります。

汎用化しすぎて呼び出されなくなる失敗例

最も起こりやすい失敗は、「とりあえず作業手順を全部書いておく」と汎用Skillsを1つだけ用意するケースです。SKILL.mdの説明文が広範になりすぎると、Antigravity側がどのタイミングで呼び出すべきか判断できず、結果としてどの場面でも発火しないまま放置されます。

逆に、似たSkillsを複数作って説明文が重複していると、エージェントがどれを呼ぶべきか判断に迷い、意図しないSkillsが選ばれる原因になります。粒度設計の段階で「このSkillsはこの場面で呼ぶ」という発火条件を一意に絞り込めるかを検証しておくべきです。

既存業務からSkillsを切り出す3つの観点

新規で粒度を考えるより、既存の業務手順から逆算して切り出すほうが現実的です。次の3観点で棚卸しすると判断がしやすくなります。

• 頻度：週1回以上発生する作業を優先する
• 再現性：誰がやっても同じ手順で済む作業を優先する
• 境界の明確さ：開始条件と完了条件を一文で説明できる作業を優先する

頻度が低い作業は型化のメリットが小さく、再現性が低い作業はSkillsに書き起こしても結局その場の判断が必要になります。境界が曖昧な作業は、そもそもSkillsの発火条件を定義しづらいため、まず業務側を整理するところから始めるべきです。

Antigravity Skillsの作り方

Skillsの作成は、ディレクトリ作成、SKILL.mdの記述、動作確認の3ステップで進めます。手順自体はシンプルですが、命名と発火条件の設計で品質が決まります。

Skillsの命名ルールと発火条件

SkillsはディレクトリIDがそのまま識別子になるため、命名は機能を端的に表す英語小文字とハイフンの組み合わせが扱いやすいです（例：release-checklist、generate-pr-description）。

SKILL.mdの冒頭には、Skillsの名前と説明をフロントマターで記述し、Antigravityが「いつこのSkillsを呼ぶべきか」を判断する材料を提供します。

説明文は具体的な作業内容と発火条件を1〜2行で書くのが効果的で、抽象的な表現や複数の用途を詰め込むと、エージェントが選択を誤る原因になります。

配置場所は、個人利用なら ~/.gemini/skills/<skill-id>/SKILL.md、プロジェクト共有なら .agent/skills/<skill-id>/SKILL.md が基本です。

参照ファイルと依存Skillsの設定

SKILL.md本体に書き切れない手順や、定型のスクリプト・テンプレートは、同じディレクトリに別ファイルとして置き、SKILL.md内から相対パスで参照させます。

たとえばリリース手順のSkillsであれば、SKILL.mdから scripts/release.sh や templates/changelog.md を参照する構成になります。

複数のSkillsから共通で使われる基礎処理がある場合は、関数単位のSkillsとして切り出し、業務単位のSkillsから内部的に呼び出す形に整理すると、変更時の影響範囲を限定できます。

動作確認とテストパターン

Skillsを作成したら、想定される発火条件を満たすプロンプトを実際に投げて、意図通りに呼び出されるかを確認します。テストパターンとして次の3つは最低限押さえておくべきです。

• 想定通りの場面で正しく発火するか
• 想定外の場面で誤発火しないか
• 複数のSkillsが該当しうる場面で意図したSkillsが選ばれるか

テスト時には、Agent ManagerのログでどのSkillsが読み込まれたかを必ず確認します。期待と異なるSkillsが選ばれている場合は、説明文の表現を絞り込むか、競合するSkillsの説明文を見直すことで改善できます。

Antigravity Skillsが呼び出されないときの確認方法

Skillsが意図通りに動かない原因の多くは、プロンプト・Skills間の競合・参照範囲の3つに集約されます。原因を切り分ける順序を決めておくと、デバッグの時間を短縮できます。

プロンプト不足で発火しないケース

最も多いのは、プロンプト側にSkillsの発火条件を満たす情報が含まれていないケースです。Skillsの説明文が「リリース作業の前準備をする」となっているのに、ユーザーの指示が「あれやっといて」のように抽象的だと、Antigravityは関連性を判断できず、Skillsを呼び出しません。

確認手順としては、まずSkillsのSKILL.mdに書いた発火条件を読み返し、現在のプロンプトがその条件を明示的に含んでいるかをチェックします。含まれていなければ、プロンプトに業務名や工程名を1語入れるだけで解消することが多いです。

競合するSkillsが存在するケース

複数のSkillsで説明文が似通っていると、エージェントがどれを呼ぶべきか判断できず、別のSkillsが優先される、または何も呼ばれないという状態になります。確認手順は次の通りです。

• 同じディレクトリ階層に説明文が重複するSkillsがないかを検索する
• 業務単位とタスク単位のSkillsで発火条件が被っていないかを照合する
• グローバル配置（~/.gemini/skills/）とワークスペース配置（.agent/skills/）で同名Skillsが両方存在しないかを確認する

競合が見つかった場合は、説明文を「いつ、どの場面で呼ばれるべきか」が一意に判断できる表現に絞り込むのが基本対応です。

参照範囲のミスでエラーが出るケース

Skillsが発火しても、参照ファイルのパス指定が誤っていたり、依存するスクリプトが存在しなかったりすると、実行途中でエラーになります。

SKILL.mdから相対パスで参照する場合は、Skillsディレクトリのルートからの相対位置になっているかを確認します。

また、グローバル配置のSkillsからプロジェクト固有のファイルを参照しているケースも、パス解決に失敗する典型例です。

参照ファイルはSkillsディレクトリ内に閉じる、もしくはプロジェクト依存のものはワークスペース配置に切り出す、というルールを設けておくと事故を防げます。

Antigravity Skillsをチームで運用するルール

Skillsは作って終わりではなく、誰がいつ更新し、いつ廃止するかまでを決めて初めて運用に乗ります。個人利用と同じ感覚でチーム導入すると、放置されたSkillsが増え、エージェントの選択精度を下げる原因になります。

Skillsの共有・更新・廃止のサイクル

チーム共有するSkillsはワークスペース配置（.agent/skills/）に置き、リポジトリでバージョン管理するのが基本です。共有時には、追加・更新・廃止のそれぞれにレビュー観点を決めておくと品質が安定します。

操作	主なレビュー観点
追加	発火条件が一意に判断できるか、既存Skillsと競合しないか
更新	既存の発火パターンを壊していないか、参照ファイルが整合しているか
廃止	他のSkillsから依存されていないか、利用実績を確認したか

廃止判断では、Agent Managerの実行ログを参照して直近の利用頻度を確認し、3か月以上呼ばれていないSkillsはアーカイブ候補として扱うと、無駄な並存を避けられます。

バージョン管理と変更履歴の追跡

SKILL.mdの内容変更は、Gitなどのバージョン管理ツールで履歴を残し、変更理由をコミットメッセージに必ず添えます。Skillsの説明文を変更すると発火タイミングが変わるため、エージェントの動作が突然変わったように見える事態を避けるためにも、変更履歴の追跡は欠かせません。

プルリクエスト時にはSKILL.mdの差分を必ず読む運用にし、説明文・発火条件・参照パスのいずれかが変わっていれば、テストパターンの再実行を必須化するのが安全です。

使う側と作る側のガバナンス

Skillsを作る側と使う側の責任範囲を分けておくと、運用が属人化しません。作る側は粒度設計・発火条件・テストパターンを担当し、使う側はSkillsの呼び出し方とレビュー観点を担当する、という線引きが基本になります。

社内に複数のチームがある場合は、Skillsの命名規則（プレフィックスでチーム識別など）と配置ルールを先に整え、グローバル領域とワークスペース領域の使い分けも明文化しておくと、Skillsの増加に伴う管理負荷を抑えられます。

弊社エンジニアからのコメント：

チーム導入の初期に「便利そうな手順は全部Skillsにしよう」と20個ほど一気に作成したことがあるのですが、説明文が似通ってしまい、エージェントがどのSkillsを呼ぶべきか毎回判断に迷う状態になりました。

結果、一部のSkillsはほぼ呼ばれず、別のSkillsが意図せず優先される事態が頻発します。導入直後は5〜10個に絞り、説明文を1行で書き分けられる粒度から始めるのが安全です。Skillsの数を絞り込むほど、エージェントの選択精度は上がります。

まとめ

AntigravityのSkillsは、業務手順や開発フローを型化してエージェントに記憶させ、AI活用の再現性を担保する機能です。要点は次の3つです。

• 粒度設計を先に決め、業務単位・タスク単位・関数単位のレイヤーで整理してから作成する
• 動作しないときはプロンプト不足・Skills競合・参照範囲の3軸で原因を切り分ける
• チーム運用では共有・更新・廃止のサイクルとバージョン管理ルールを最初に決めておく

AIzen株式会社では、AIを組み込んだ業務アプリ開発から開発フロー設計、Skillsを含むエージェント運用ルールの整備までを支援しています。

Skillsの粒度設計や運用ルールづくりで迷う場合は、貴社の業務要件に合わせた整理から無料でご相談を承ります。