---
title: "Gemini CLI で Agent Skills をマスターする"
date: 2026-01-29
lastmod: 2026-01-29
description: "Gemini CLI における Agent Skills の構築と設定方法を解説。段階的開示（Progressive Disclosure）、オンデマンドなプロンプト読み込み、決定論的な Python 分析スクリプトの活用法を網羅。"
categories: ["Agentic Coding"]
tags: ["agent-skills","gemini-cli","mcp","vibe-coding"]
url: https://danicat.dev/ja/posts/agent-skills-gemini-cli/
---

# Gemini CLI で Agent Skills をマスターする

- **URL**: https://danicat.dev/ja/posts/agent-skills-gemini-cli/
- **Author**: ダニエラ・ペトルザレク
- **Date**: 2026-01-29
- **Categories**: Agentic Coding
- **Summary**: Gemini CLI における Agent Skills の構築と設定方法を解説。段階的開示（Progressive Disclosure）、オンデマンドなプロンプト読み込み、決定論的な Python 分析スクリプトの活用法を網羅。

---
> **追記 (2026年):** Gemini CLI は **Google Antigravity 2.0** へと進化しました。本記事で解説している Agent Skills の基本概念や構造は引き続き有効ですが、プラットフォームの概要については [Antigravity 2.0 への銀河ヒッチハイク・ガイド](https://danicat.dev/ja/posts/20260521-the-hitchhikers-guide-to-antigravity-2-0/) を、本番環境向けの最新パターンやスキルカタログ、トークン最適化については [Agent Skills 実践ガイド](https://danicat.dev/ja/posts/20260829-the-pragmatic-guide-to-agent-skills/) をご覧ください。

先週 [Tenkai](https://danicat.dev/ja/posts/20260120-improving-agentic-coding-with-science/) について記事を書いた際、実験分析に関する重要な側面——「実験結果からいかにして洞察を抽出するか」については触れませんでした。サマリーや統計指標、検定結果を確認できる使い勝手のよいフロントエンドはあるものの、単なるサマリーから各設定の微妙なニュアンスを汲み取るのは非常に困難です。

たとえば、ファイルの読み取り操作（`read_file` や godoctor の `smart_read` など）は、タスクが失敗したシナリオや完了までに時間がかかったシナリオと強い相関があることにしばしば気づきます。これは読み取り操作自体が悪いからでしょうか？いいえ、エージェントがエラーから復帰するために、ソースコードを再度読み直して知識をリフレッシュする必要があったからです。つまり、読み取り操作の多さと処理の遅延や失敗との間には強い相関関係があるものの、決して因果関係があるわけではありません。統計学者が言うように、「相関関係は因果関係を意味しない（相関は因果ではない）」のです。

ここ数週間数多くの実験を重ねる中で、毎回モデルに対してより深い分析を行うよう指示するのはあまり効果的ではないとすぐに気づきました。通常このようなシナリオでは、エージェントのコンテキスト（`GEMINI.md` など）に分析指示を追加するか、必要なプロンプトを MCP サーバーに格納してスラッシュコマンドにマッピングするかのいずれかを行います。

どちらのアプローチも機能はしますが、それぞれに限界があります。実行したいタスクごとにエージェントのコンテキストを拡張していくと、コンテキストの肥大化（context bloat）を招き、エージェントの動作精度が低下します。一方でプロンプトごとにスラッシュコマンドを作成する場合、エージェントは設計上それらのコマンドの存在を認識できないため、人間が明示的にコマンドを呼び出さなければなりません。

幸いなことに、**Agent Skills** はこの両方の強みを組み合わせたソリューションを提供してくれます。Agent Skills は [Gemini CLI](https://geminicli.com) の新機能で、エージェントへオンデマンドに専門能力を付与するために設計されました。エージェントツールと同様に動作します（実際、スキルはツール呼び出しによってアクティブ化されます）が、スキルを使うことで、エージェントが専門的なタスクを実行するために必要なプロンプトや補助ファイルにオンデマンドでアクセスでき、必要なタイミングでのみそれらをコンテキストに読み込むことができます。

完全な技術仕様は[公式ドキュメント](https://geminicli.com/docs/cli/skills/)に記載されていますが、本記事では使い始めるための基本を解説します。

## スキルの基本構造

スキルとは、プロンプトと、必要に応じてドキュメントやスクリプトなどの補助ファイルをまとめたフォルダに過ぎません。

```text
my-skill/
├── SKILL.md       (必須) 指示とメタデータ
├── scripts/       (オプション) 実行可能なスクリプトやツール
├── references/    (オプション) 静的なドキュメントやリファレンス例
└── assets/        (オプション) テンプレートやバイナリリソース
```

`SKILL.md` はスキルの指示プロンプトを記述するファイルです。スキル名と説明文（description）を定義する簡潔なフロントマターを持ちますが、それ以外は通常の Markdown ファイルです。

```text
---
name: <一意のスキル名>
description: <スキルが何を行うか、Gemini がいつ使用すべきかの説明>
---

<エージェントの振る舞いやスキルの使用手順に関する指示>
```

プロジェクトにスキルを追加するには、`.gemini/skills` 配下にフォルダを作成します。たとえば上記の `my-skill` であれば、`.gemini/skills/my-skill` に配置します。Gemini CLI は、以下の優先順位に従ってスキルを自動的に探索します。

1. **Workspace** (`<プロジェクト名>/.gemini/skills`)
2. **User** (`~/.gemini/skills`)
3. **Extensions** (`~/.gemini/extensions/<拡張機能名>/skills`)

ここで重要なのは、Gemini CLI の起動時点ではスキルの名前（name）と説明（description）のみが認識されているという点です。それ以外のファイルや詳細な指示はすべて、スキルがアクティブ化された際に初めて**オンデマンド**で読み込まれます。

それでは、実験分析ワークフローを改善するために、私が実際にどのようにスキルを活用しているかを見ていきましょう。

## `experiment-analyst` スキル

私は `experiment-analyst` スキルを、Gemini CLI に実験の評価を依頼したときにアクティブ化されるよう設計しました。ディレクトリ構成は以下のようになっています。

```text
experiment-analyst/
├── SKILL.md                     <-- 分析ガイドライン
├── references/
│   └── tenkai_db_schema.md      <-- データベーススキーマ。エージェントが毎回自力で探索する必要を省く
└── scripts/
    ├── analyze_experiment.py    <-- フロントエンドで行っている分析の一部を再現
    ├── analyze_patterns.py      <-- 洞察を抽出するために共通パターンを深掘り
    ├── get_experiment_config.py <-- 実験設定の詳細を取得
    └── success_determinants.py  <-- ツール呼び出しの分析と相関の算出
```

### 専門家のペルソナを定義する

`SKILL.md` ファイルには、分析の手順や規律を定義します。エージェントに何をすべきかを教えつつも、単なる機械的で型通りの振る舞い（cookie-cutter）にならないようバランスを取っています。重要なポイントの一つは、エージェントが安易に結論へ飛びつくのを防ぎ、より堅実で客観的なペルソナを確立することです。私自身、エージェントのすべての主張を検証し、すべての結論を慎重に受け止めるようにしていますが、このバージョンによって、手動では発見に多大な労力を要したであろう興味深い洞察を数多く得ることができました。

```text
---
name: experiment-analyst
description: Expertise in analysing Tenkai agent experiments. Use when asked to "analyse experiment X" to determine success factors, failure modes, and behavioural patterns.
---

# Experiment Analyst

## Core Mandates
1. **Evidence-Based:** Never make claims without data. Cite specific Run IDs.
2. **Correlation ≠ Causation:** A tool might be correlated with failure (e.g., `read_file`) because it's used for recovery. Always investigate the *context* of usage.
3. **Comparative:** Always contrast the performance of alternatives.
```

注: [SKILL.md の完全な内容](https://github.com/danicat/skills/blob/main/experiment-analyst/SKILL.md) はこちらから確認できます。

### スキルのアセット

今後数週間にわたってこの話題を何度も取り上げることになりますが、本質的に**非決定論的（non-deterministic）**であるエージェントを扱う際、品質を担保する唯一の方法は、エージェントに**決定論的（deterministic）**なツールを提供することです。スキルはこの哲学に見事に合致しています。タスクの実行方法をエージェントの「推測」に委ねるのではなく、一貫した方法でタスクを実行するスクリプトを同梱できるからです。

実験分析スキルの作成にあたり、エージェントに自由な探索の余地を残しつつも、毎回車輪の再発明をしてほしくはありませんでした。そのため、以下のような事前パッケージ化されたスクリプトを同梱しています。

- `analyse_experiment.py`: フロントエンドにあるものと同様の実験サマリーを再現しつつ、シェルコマンドのツール呼び出しを適切にグルーピング
- `analyse_patterns.py`: ツール利用パターンを特定するために、エージェントの会話履歴からサンプルを抽出
- `get_experiment_config.py`: 実験定義を取得し、エージェントが実験設定を正確に把握できるよう支援
- `success_determinants.py`: タスクの成功結果とツール呼び出しの相関関係を算出

また、エージェントがアドホックなクエリを実行することを選んだときのために、`references/tenkai_db_schema.md` でデータベーススキーマを提供しています。これにより、エージェントは毎回スキーマを探索し直す必要がなくなります（このスキーマは実行間で比較的安定しています）。

この構成が完璧だと言うつもりはありませんし、まだ洗練に膨大な時間を費やしたわけでもありません。しかし、この情報と事前パッケージ化されたスクリプトの組み合わせによって、私が普段エージェントに探索させたい質問の大部分を十分にカバーできています。

## おわりに

Agent Skills は、エージェントワークフローの設計における重要なパラダイムシフトを示しています。巨大なコンテキストプロンプト（`GEMINI.md` にすべてを詰め込むなど）から脱却し、モジュール化されたオンデマンドの機能へと移行することで、私たちは2つの課題を同時に解決できます。エージェントのコンテキストをクリーンに保ち（トークン消費を抑え）、汎用的な推論パフォーマンスを犠牲にすることなく、高度に専門化された専門知識を発揮させることができるのです。

私の場合、`experiment-analyst` スキルのおかげで、退屈で反復的な作業を半自動化されたフローへと昇華させることができました。求めている分析を実行するための十分な一貫性と柔軟性が手に入りました。現在、MCP サーバーを「プロンプトのデータベース」として使用していた従来のアプローチから移行し、ワークフローの他の部分もスキルへと順次アップグレードすることを検討しています。

コミュニティの皆さんがどのようなスキルを構築されるか、今から非常に楽しみです。ぜひご自身のワークフローを見つめ直してみてください。毎回繰り返し指示を与えている部分はありませんか？専任の専門家を必要としている場面はありませんか？それこそが、次に作成すべきスキルの候補です。

**追記:** 実践的なユースケースを掘り下げた [パート2: skill-creator で Agent Skills を構築する](https://danicat.dev/ja/posts/20260227-gemini-cli-skills-part-2/) を公開しました。あわせてご覧ください。

Happy coding!