◀ ガイドTOP Agent Skills
対象中級者
達成目標カスタムSkill作成
前提知識Ch.1-3完了
所要時間25分

Agent Skills

SKILL.mdの作成からスコープ設計、5つのスキルパターンまで。エージェントを汎用AIから専門家に変えるSkillsシステム。

Agent Skillsとは

Agent Skillsは、汎用的なAIモデルを特定のタスクの「専門家」に変えるための仕組みです。SKILL.mdファイルに定義された指示・参照情報・手順がエージェントのコンテキストにロードされ、タスクに最適化された振る舞いを実現します。

なぜSkillsが必要なのか

SkillとGEMINI.mdの違い

項目 GEMINI.md SKILL.md
ロードタイミング 常にロード 必要時のみロード
スコープ プロジェクト全体 特定のタスク
内容 プロジェクト概要・規約 タスク固有の手順・参照情報
長さの目安 80〜120行 50〜300行（パターンによる）
更新頻度 月1回程度 手順変更時に随時
📝 Note

Skillsは「エージェントが呼び出す辞書」と考えてください。すべての情報をGEMINI.mdに詰め込むとコンテキストが溢れます。共通の指示はGEMINI.md、タスク固有の詳細はSkillsに分離するのがベストプラクティスです。

SKILL.md の構造

SKILL.mdはYAMLフロントマターとMarkdownボディで構成されます。フロントマターにメタ情報を、ボディに具体的な指示を記述します。

基本構造
--- name: deploy-production description: "本番環境へのデプロイ手順を実行するスキル" trigger: "deploy, デプロイ, 本番反映, リリース" model: gemini-3-pro temperature: 0.0 --- # Deploy Production ## 前提条件 - mainブランチにいること - 全テストがパスしていること - CHANGELOG.mdが更新されていること ## 手順 1. テストの実行 ```bash npm run test:all ``` 2. ビルド ```bash npm run build:production ``` 3. デプロイ前チェック - ビルドアーティファクトのサイズを確認（前回比+10%以上なら警告） - 環境変数の設定を確認 4. デプロイ実行 ```bash gcloud run deploy my-service \ --image gcr.io/my-project/my-service:latest \ --region asia-northeast1 \ --platform managed ``` 5. ヘルスチェック ```bash curl -f https://api.example.com/health || echo "DEPLOY FAILED" ``` ## 注意事項 - デプロイは平日10:00-17:00のみ実行可能 - 金曜日のデプロイは禁止（週末のインシデント対応を避けるため） - ロールバック手順: `gcloud run services update-traffic --to-revisions=PREVIOUS=100`

フロントマターのフィールド

フィールド 必須 説明
name 必須 スキルの一意識別名。ケバブケース推奨（例: deploy-production）
description 必須 スキルの説明。エージェントがスキルを選択する際の判断材料
trigger 推奨 スキルを起動するキーワード（カンマ区切り）。ユーザーの発話にキーワードが含まれると自動的にロード
model 任意 このスキルで使用するモデル。省略時はデフォルトモデルを使用
temperature 任意 生成のランダム性（0.0〜1.0）。手順実行は0.0、クリエイティブ作業は0.7推奨
✅ Tip

description は最も重要なフィールドです。エージェントが「どのスキルを使うか」を判断する際に参照するため、具体的で正確な説明を書いてください。曖昧な説明は誤ったスキル選択につながります。

✅ トリガーキーワード設計のコツ

SKILL.mdのdescriptionフィールドは、エージェントがスキルを選択する際のトリガーになります。「デプロイする」「テストを書く」「コードレビューして」など、ユーザーが実際に使う自然言語フレーズを含めましょう。多言語対応する場合は、日本語と英語の両方のキーワードを記載します。

スキルのスコープ設計

Skillsはワークスペーススコープとグローバルスコープの2層で管理できます。プロジェクト固有のスキルと汎用スキルを分離することで、メンテナンス性が向上します。

📝 設定ファイルのスコープとの違い

GEMINI.mdや.agent/config/の設定スコープについてはCh.2「プロジェクト構成設計」を参照してください。ここではSkills固有のスコープ設計について説明します。

ワークスペーススコープ

プロジェクトの .agent/skills/ ディレクトリに配置します。プロジェクト固有のタスク（デプロイ、データ移行、特定のテスト実行など）に使用します。

ワークスペーススキルの配置
my-project/ └── .agent/ └── skills/ ├── deploy/ │ └── SKILL.md # 本番デプロイ手順 ├── db-migration/ │ └── SKILL.md # DBマイグレーション手順 ├── api-test/ │ ├── SKILL.md # APIテスト実行手順 │ └── test-data.json # テストデータ（参照ファイル） └── code-review/ └── SKILL.md # コードレビューチェックリスト

グローバルスコープ

~/.gemini/antigravity/skills/ に配置します。プロジェクトに関係なく使用する汎用スキル（Gitワークフロー、ドキュメント生成、リファクタリングパターンなど）に使用します。

グローバルスキルの配置
~/.gemini/antigravity/ └── skills/ ├── git-workflow/ │ └── SKILL.md # Git操作の標準手順 ├── documentation/ │ └── SKILL.md # ドキュメント生成ルール ├── security-audit/ │ └── SKILL.md # セキュリティチェック └── performance/ └── SKILL.md # パフォーマンス分析手順
スコープ 場所 Git管理 適切な用途
ワークスペース .agent/skills/ チーム共有推奨 デプロイ、DB操作、PJ固有テスト
グローバル ~/.gemini/antigravity/skills/ 個人（dotfiles管理可） Git操作、ドキュメント生成、セキュリティ
📝 Note

同名のスキルがワークスペースとグローバルの両方にある場合、ワークスペースのスキルが優先されます。これにより、汎用スキルをプロジェクト固有にオーバーライドできます。

Progressive Disclosure（段階的開示）

Skillsが解決する最大の課題は、システムプロンプトの肥大化です。すべてのルールをGEMINI.mdに書くと、コンテキストウィンドウを無駄に消費し、重要な指示が埋もれます。

Skillsは「Progressive Disclosure（段階的開示）」のパターンで、必要な時だけ知識をロードします。

1

常時ロード（GEMINI.md）

すべてのタスクに適用される基本ルール：セキュリティ、コーディング規約、言語設定。80〜120行に抑える。

2

必要時ロード（Skills）

特定タスクの専門知識：デプロイ手順、DB操作、テストパターンなど。ユーザーのリクエストがSkillのdescriptionと一致した時だけロード。

3

手動呼び出し（Manual Skills）

頻度の低い作業：マイグレーションガイド、リリース手順など。ユーザーが明示的に呼び出した場合のみ。

📝 Note

Skillsの仕組みにより、GEMINI.mdを100行以下に保ちつつ、数十ページ分の専門知識をエージェントに持たせることができます。「常に必要なもの」と「たまに必要なもの」を明確に分けましょう。

実践的な5つのスキル例

よく使われる具体的なSkill活用パターンです。

# スキル名 用途 パターン
1 Git Commit整形 Conventional Commitsに準拠したメッセージ生成 Basic Router
2 ライセンスヘッダー追加 新規ファイルにライセンスヘッダーを自動追加 Reference
3 JSON→Pydantic変換 JSONスキーマからPydanticモデルを自動生成 Few-shot
4 DBスキーマ検証 マイグレーションファイルの整合性チェック Tool Use
5 資料作成・リサーチ 技術調査結果のMarkdownレポート生成 All-in-One

スキル設計フロー

スキルを新しく作成する前に、以下の3ステップで設計方針を固めましょう。

1

タスクの特定

繰り返し発生するタスクを洗い出します。週に3回以上使うパターンはスキル化の候補です。手動で毎回同じプロンプトを書いているなら、それはスキルにすべきサインです。

2

汎用 vs 特化の判断

プロジェクト固有ならワークスペーススコープ、全プロジェクト共通ならグローバルスコープに配置します。迷ったらまずワークスペースに作り、汎用性が確認できてからグローバルに昇格させましょう。

3

パターン選択

タスクの複雑さに応じて5パターンから選択します。シンプルなものはBasic Router、外部参照が必要ならReferenceパターンが適しています。下記の5パターンを参照してください。

5つのスキルパターン（構造）

Skillsの設計には5つの基本パターンがあります。タスクの性質に応じて最適なパターンを選択してください。

1

Basic Router

最もシンプルなパターン。SKILL.mdに短い手順を記述するだけ。単一コマンドの実行や、簡単なチェックリストに適しています。50行以下が目安です。

2

Reference

外部ドキュメントや設定ファイルを参照するパターン。SKILL.mdから別ファイル（API仕様書、設定例など）をインクルードして、エージェントに豊富な参考情報を提供します。

3

Few-shot

入力/出力の具体例を含めるパターン。コードレビューコメントのトーン、エラーメッセージの書き方など、「こう書いてほしい」という例を提示して品質を制御します。

4

Tool Use

MCPサーバーやCLIツールとの連携を定義するパターン。「Slack通知を送る」「JIRAチケットを更新する」など、外部ツールとの統合手順を記述します。

5

All-in-One

上記パターンを組み合わせた包括的なスキル。複雑なワークフロー（PR作成→レビュー→デプロイ→通知）を1つのスキルで完結させます。200〜300行が目安です。

パターン比較

パターン 行数目安 参照ファイル 適切な場面
Basic Router 20〜50行 なし 単一コマンド、簡単なチェック
Reference 50〜100行 1〜3ファイル API仕様準拠、設定テンプレート
Few-shot 80〜150行 なし コードレビュー、文書生成
Tool Use 50〜120行 MCPサーバー設定 外部ツール連携、通知
All-in-One 200〜300行 複数ファイル エンドツーエンドワークフロー

Reference パターンの例

.agent/skills/api-endpoint/SKILL.md
--- name: create-api-endpoint description: "API仕様に準拠した新しいエンドポイントを作成する" trigger: "エンドポイント作成, API追加, 新しいAPI" --- # Create API Endpoint 新しいAPIエンドポイントを作成する際は、以下の仕様に従ってください。 ## 参照ファイル - `docs/api-spec.yaml` - OpenAPI仕様書 - `internal/api/middleware.go` - 認証・ログミドルウェア - `internal/api/handler_example.go` - ハンドラの実装例 ## 実装手順 1. OpenAPI仕様書にエンドポイント定義を追加 2. `internal/api/` にハンドラファイルを作成 3. `internal/domain/` にビジネスロジックを実装 4. `internal/infra/` にリポジトリ実装を追加 5. ルーティングに新エンドポイントを登録 6. テーブル駆動テストを作成 ## 必須チェック - [ ] OpenAPI仕様との整合性 - [ ] 認証ミドルウェアの適用 - [ ] バリデーション（入力検証） - [ ] エラーレスポンスの統一 - [ ] テストカバレッジ80%以上

Few-shot パターンの例

.agent/skills/code-review/SKILL.md
--- name: code-review description: "プロジェクト規約に基づいたコードレビューを実行する" trigger: "レビュー, review, コードチェック" temperature: 0.2 --- # Code Review ## レビューコメントのトーン（Few-shot Examples） ### 良い例 - "この変数名を `userEmail` から `recipientEmail` に変更すると、メール送信の文脈がより明確になります" - "ここで early return を使うとネストが1段浅くなり、可読性が向上します" - "このクエリにインデックスが効いているか確認してください。users テーブルの email カラムにインデックスはありますか？" ### 悪い例（避けるべきトーン） - "この書き方はダメです" → 代替案なしの否定 - "なんでこう書いたんですか？" → 攻撃的な質問 - "普通はこう書きます" → 根拠のない慣習の押し付け ## チェック項目 1. エラーハンドリングの漏れ 2. N+1クエリ 3. 未使用のインポート/変数 4. ハードコードされた値（マジックナンバー） 5. テストの欠如

スキル作成実践

実際にデプロイスキルを作成するステップバイステップの実践です。

  1. ディレクトリを作成
    .agent/skills/deploy-staging/ ディレクトリを作成します。スキル名はケバブケースで、用途が一目でわかる名前にしてください。
  2. SKILL.md を作成
    YAMLフロントマターに name、description、trigger を記述します。description はエージェントが適切にスキルを選択できるよう、具体的な説明を書いてください。
  3. 手順を記述
    Markdownボディに具体的な手順を記述します。コマンドはコードブロックで囲み、条件分岐や注意事項も明記します。
  4. テスト実行
    エージェントパネルでトリガーキーワードを含む指示を出し、スキルが正しくロードされるか確認します。例: 「ステージング環境にデプロイして」
  5. 反復改善
    エージェントの出力を確認し、不足している情報や曖昧な手順があれば SKILL.md を修正します。2〜3回の反復で実用的なスキルが完成します。
.agent/skills/deploy-staging/SKILL.md（完成例）
--- name: deploy-staging description: "ステージング環境へのデプロイ手順。テスト→ビルド→デプロイ→ヘルスチェックの一連の流れを実行する" trigger: "ステージング, staging, ステージングデプロイ" model: gemini-3-pro temperature: 0.0 --- # Deploy to Staging ## 前提条件チェック - [ ] developブランチの最新状態であること (`git pull origin develop`) - [ ] ローカルテストが全てパスしていること - [ ] .env.staging ファイルが存在すること ## 手順 ### 1. テスト実行 ```bash npm run test:unit && npm run test:integration ``` 全テストがパスしない場合は中断してエラーを報告してください。 ### 2. ビルド ```bash NODE_ENV=staging npm run build ``` ### 3. Dockerイメージのビルドとプッシュ ```bash docker build -t gcr.io/my-project/my-app:staging-$(git rev-parse --short HEAD) . docker push gcr.io/my-project/my-app:staging-$(git rev-parse --short HEAD) ``` ### 4. デプロイ ```bash kubectl set image deployment/my-app \ my-app=gcr.io/my-project/my-app:staging-$(git rev-parse --short HEAD) \ --namespace=staging ``` ### 5. ヘルスチェック（30秒待機後） ```bash sleep 30 curl -f https://staging.example.com/health ``` ## トラブルシューティング - イメージプッシュ失敗: `gcloud auth configure-docker` を実行 - Pod起動失敗: `kubectl logs -n staging deployment/my-app` でログ確認 - ヘルスチェック失敗: 前のリビジョンにロールバック ## ロールバック手順 ```bash kubectl rollout undo deployment/my-app --namespace=staging ```
⚠️ Warning

SKILL.mdにシークレット（APIキー、パスワード、トークンなど）を直接記述しないでください。環境変数やシークレットマネージャーを参照する形で記述します。SKILL.mdはGitにコミットされるため、機密情報が漏洩するリスクがあります。

スキル管理

スキルの数が増えてきたら、効率的な管理方法を導入しましょう。

CLIからのスキル管理

コマンドパレット / ターミナル
# インストール済みスキル一覧 antigravity skills list # スキルの詳細表示 antigravity skills show deploy-staging # Gitリポジトリからスキルをインストール antigravity skills install https://github.com/team/shared-skills.git # スキルの有効化/無効化 antigravity skills enable deploy-staging antigravity skills disable deploy-staging # スキルの削除 antigravity skills remove deploy-staging

Gitリポジトリからのインストール

チーム共有のスキルライブラリをGitリポジトリで管理し、各プロジェクトからインストールできます。

共有スキルリポジトリの構成
team-skills/ ├── README.md ├── deploy/ │ └── SKILL.md ├── code-review/ │ └── SKILL.md ├── security-audit/ │ └── SKILL.md └── documentation/ └── SKILL.md
インストールコマンド
# リポジトリ全体をインストール antigravity skills install https://github.com/team/shared-skills.git # 特定のスキルのみインストール antigravity skills install https://github.com/team/shared-skills.git --skill deploy # 特定のブランチ/タグからインストール antigravity skills install https://github.com/team/shared-skills.git --ref v2.0.0

Symlink方式

チーム全体で同一のスキルリポジトリをクローンし、シンボリックリンクで各プロジェクトに紐付ける方法もあります。

Symlink方式の設定
# 共有スキルリポジトリをクローン git clone https://github.com/team/shared-skills.git ~/team-skills # プロジェクトのスキルディレクトリにシンボリックリンク cd my-project/.agent/skills ln -s ~/team-skills/deploy deploy-shared ln -s ~/team-skills/code-review code-review-shared
✅ Tip

スキルの品質を維持するために、スキルリポジトリにもCIを設定しましょう。SKILL.mdのフロントマターバリデーション、Markdownリンティング、必須フィールドのチェックを自動化することで、壊れたスキルの混入を防げます。

スキルの有効化/無効化

プロジェクト設定でスキルの有効/無効を制御できます。不要なスキルを無効化することで、エージェントの判断精度が向上します。

.agent/config/settings.json
{ "skills": { "enabled": [ "deploy-staging", "code-review", "api-endpoint" ], "disabled": [ "deploy-production" ], "autoDetect": true } }
📝 Note

autoDetect: true の場合、エージェントがユーザーの発話からトリガーキーワードを検出し、自動的にスキルをロードします。false にすると、明示的にスキル名を指定する必要があります（例: /skill deploy-staging）。

スキルのバージョン管理

スキルが増えてくると、バージョン管理が重要になります。特にチームで共有するスキルは、変更履歴を追跡できる仕組みが必要です。

Semantic Versioning の適用

スキルにも MAJOR.MINOR.PATCH のバージョニングを適用することを推奨します。

CHANGELOG.mdの運用

各スキルディレクトリに CHANGELOG.md を配置し、変更履歴を記録します。

CHANGELOG.md の例
# Changelog - deploy-staging skill ## [2.0.0] - 2026-03-15 ### Breaking Changes - デプロイ先をCloud RunからCloud Functionsに変更 - 環境変数 `DEPLOY_TARGET` が必須に ### Added - ヘルスチェックの自動実行ステップを追加 ## [1.1.0] - 2026-02-20 ### Added - Slack通知オプションを追加（`--notify` フラグ） ## [1.0.0] - 2026-01-10 ### Initial Release - ステージング環境へのデプロイ手順を定義

破壊的変更時の運用

MAJORバージョンを上げる破壊的変更を行う場合は、チームへの通知が必要です。既存のワークフローが壊れる可能性があるため、移行期間を設けることを推奨します。

📝 スコープの優先順位

同名スキルがワークスペースとグローバルの両方にある場合、ワークスペースが優先されます。意図しないオーバーライドを防ぐため、グローバルスキルには名前にプレフィックス（例: global-deploy）を付けることを推奨します。

← 前のページ
Editor & Manager