organise-agent-skills

エージェントスキルの整理

重要

ユーザー確認必須のガードレール：エージェントは、監査結果、提案するアクション、トークン指標をユーザーに提示し、実行する明示的な確認を得る前に、スキルのディレクトリを削除したり、設定ファイル（skills.json）でスキルを無効化／有効化したり、設定／ルールのドキュメント（GEMINI.md、AGENTS.md、README.md）を変更したりしてはなりません。

このスキルでは、Antigravity および Gemini 環境でエージェントスキルを監査、削減、整理するための、再現可能で構造化されたワークフローを提供します。インストール済みのすべてのスキルへのアクセスを維持しながら、プロンプトのコンテキストウィンドウを軽量（アクティブなスキル約30～50個／やり取り1ターンあたりのオーバーヘッド約3,000トークン）に保てます。

目次

• 概要とトークン予算
• スキルのライフサイクルと状態
• ワークフロー フェーズ1：監査と検出
• ワークフロー フェーズ2：メタスキルへの委任
• ワークフロー フェーズ3：オンデマンドのルール（GEMINI.md / AGENTS.md）
• ワークフロー フェーズ4：移植性と skills.json の除外設定
• ワークフロー フェーズ5：ドキュメントの更新

---

概要とトークン予算

エージェントのターンが始まると、**インストール済みで非アクティブ（検出可能）**なすべてのスキルのnameとdescriptionが、システムプロンプトのコンテキストに挿入されます。

• 問題点：スキルが過剰に蓄積される（検出可能なスキルが100個以上ある）と、やり取りのたびに6,000～10,000トークン以上が挿入され、コンテキストの予算を浪費し、LLMの判断を難しくします（説明が重複しているために、幻覚を起こしたり誤ったスキルを選んだりします）。
• 目標とする状態：検出可能なスキルを約30～50個に絞った軽量な中核セット（プロンプトのオーバーヘッド約3,000トークン）を維持し、専門的なスキルやサブスキルはインストール済みで除外の状態にします。それ以外は、メタスキルによるルーティングとGEMINI.mdの有効化ルールを使用します。

---

スキルのライフサイクルと状態

Antigravityなどのエージェント型開発環境では、スキルは次の3つの明示的な状態で管理されます。

1. インストール済みで非アクティブ（検出可能）：これらのスキルはディスク上に存在し、エージェントから検出可能です。エージェント（例：Antigravity）の起動時に、これらのフロントマター（レベル1）が自動的にコンテキストに読み込まれます。skills.jsonでは、これらの項目に//が付けられているか、除外されていません。
2. インストール済みで除外：これらのスキルはディスク上のライブラリに保存されていますが、自動的なレベル1の読み込みから_除外_されています。そのため、エージェントがフロントマターを自動的に読み込むことはなく、会話中にエージェントがそれらの存在を直接認識することもありません。ただし、ディスク上に存在し、エージェントが利用できるため、明示的に有効化することはできます。skills.jsonでは、これらの項目は//のない通常の文字列として記載されています。
3. 有効化済み：これは実行時の状態であり、スキルのSKILL.md本文全体が現在のターンのコンテキストに読み込まれています。つまり、レベル2の読み込み、およびサポートファイルが存在し適切な場合のレベル3の読み込みです。

---

ワークフロー フェーズ 1：監査と調査

1. ファイルシステムの自動検出と全件インベントリ監査：

   • スタンドアロンのスキル：ディスク上の ~/.gemini/config/skills/（ワークスペース内の場合は .agents/skills/ も含む）に存在するすべてのスキルディレクトリを一覧表示します。
   • パッケージ化されたプラグインスキル：~/.gemini/config/plugins/*/skills/ 内のバンドルされたスキルをすべて調査します。（skills.json に記載されていないパッケージ化されたプラグインスキルは、Antigravity によってデフォルトで検出可能と見なされ、プロンプトの負荷にひそかに加算されます）。
   • skills.json（~/.gemini/config/skills.json）を読み込み、ディスク上のすべてのディレクトリと exclude 配列のエントリを比較します。
   • 不整合を特定します：
     • 新たに検出されたスキル：ディスク上に存在するものの、skills.json に記載されていないスタンドアロンのスキルフォルダー。
     • 未登録のプラグインスキル：ディスク上に存在するものの、skills.json に記載されていないプラグインスキル。
     • 孤立したエントリ：skills.json に存在するもの（// の有無を問わない）のうち、対応するディレクトリがディスク上に存在しないもの。
     • インストール済みで除外されているスキル：// 文字列のプレフィックスなしで skills.json に記載されているスキル。
     • インストール済みで非アクティブ（検出可能）なスキル：// 文字列のプレフィックス付きで skills.json に記載されているスキル。

2. プロンプトの占有量を測定します：

   • アクティブで検出可能なすべてのスキル（未登録のプラグインスキルを含む）の説明文について、単語数／トークン数を合計します。
   • 検出可能なスキルの総数が適正範囲の30～50個（約3,000～3,500トークン）を超えていないか確認します。超過すると、Antigravity のコンテキスト予算マネージャーによってスキルが自動的に削除されます。

3. 必須の意味的・機能的重複監査： エージェントは、スキルのインベントリを体系的に調査し、重複しているスキル、旧式のスキル、冗長なスキルを特定する必要があります。フォルダー名の文字列比較や文字列距離の照合だけに頼ってはいけません。

   • 意味的・方法論的な分析： 各スキルの YAML フロントマター（description）、主要な見出し、運用上の指示を解析します。フォルダー名が異なっていても、共通するソフトウェアエンジニアリングの方法論や、機能が重複するツールがないか確認します。 例：conductor という拡張プラグインは、どちらも Spec-Driven Development（SDD）ワークフローを実装しているため、スタンドアロンの spec-driven-development スキルと重複します。

   • 機能ドメインのクラスタリング： スキルを意味的なドメインごとに分類し、複数のアクティブなスキルが競合したり、ルーティングの衝突を引き起こしたりするクラスターを特定します：

     • Gemini API と SDK：例：gemini-api と gemini-api-dev／gemini-interactions-api。
     • Spec-Driven Development と計画：例：spec-driven-development と conductor／planning-and-task-breakdown。
     • ブラウザー DevTools と自動化：例：chrome-devtools と browser-testing-with-devtools／playwright-cli。
     • クラウド認証：例：gcloud-auth-verification と google-cloud-auth-verification。
     • ワークフローオーケストレーション：例：gcp-composer-troubleshooting と managed-airflow-dag-troubleshooting。
     • データプラットフォームとストレージ：BigQuery、Spark、Dataproc、GCS など。

   • パッケージ化されたプラグインによる置き換え： スタンドアロンのスキルを、公式のパッケージ化された拡張プラグイン（config/plugins/）と照合します。上流のプラグインに同じドメインをカバーするスキルがバンドルされている場合、スタンドアロン版は不要です：

     • 不要なスタンドアロンのスキルを特定し、ディスクから削除します。
     • 削除したスキルを ~/.agents/.skill-lock.json からも除去し、npx skills update -g -y によって再ダウンロードされないようにします。
     • .gitignore に、プラグインスキルのスタンドアロン版を無視する正規表現パターン（[-_]）が含まれていることを確認します。

   • 対応：実行前提案（Pre-Execution Proposal）で、冗長なスキルディレクトリの削除と、重複するバリエーションの無効化を明示的に提案します。

ワークフロー フェーズ 2：メタスキルへの委任

サブスキルを統括するマスターメタスキルを特定します。

1. マスタールーター：

   • 例：using-agent-skills スキルは、23 個のシニアエンジニアリング SDLC サブスキルを統括します。
   • 例：google-agents-cli-workflow スキルは、ADK エージェント開発のサブスキル（scaffold、code、deploy、eval、observability）を統括します。
   • 例：gcp-data-pipelines スキルは、Dataflow、Dataform、dbt、Dataproc、BigQuery のデータパイプラインツールを統括します。

2. アクション：

   • マスターメタスキルは、skills.json で有効のままにします（例："//using-agent-skills"）。
   • 子サブスキルは、skills.json で無効にします（// のない通常の文字列）。
   • マスターメタスキルにより、エージェントは必要に応じてディスク上のサブスキルファイルを調べて読み取るよう指示されます。

---

ワークフロー フェーズ 3：オンデマンドのルール（GEMINI.md / AGENTS.md）

skills.json で特化型またはニッチな分野のスキル（マスターメタスキルのサブスキルではないスキル）を無効にする場合は、エージェントが必要に応じてそのスキルを有効化または調査するタイミングを把握できるよう、GEMINI.md または AGENTS.md に有効化ルールが存在することを必ず確認してください。

1. skills.json で無効化：

   • ドメインスキルを exclude の通常の文字列として指定し、デフォルトで自動プロンプト注入の対象から除外します。

2. GEMINI.md または AGENTS.md でルールを必ず生成：

   • ## Knowledge Rules の下にある GEMINI.md（またはワークスペーススキルの場合は AGENTS.md）を確認します。
   • 無効化するドメインスキルの有効化ルールがまだ存在しない場合は、次のテンプレートを使って有効化ルールを作成し、追記する必要があります。

   ### <Domain / Skill Name> Activation Rule
   
   The `<skill-name>` skill is disabled by default in `skills.json` to keep context window overhead lean.
   
   **Activation Rule**: Activate or inspect `<skill-name>` (by adding `//` in `skills.json` or reading on demand) whenever <specific scenario, task type, or trigger conditions>.
   

   例：

   • GCS Security Assessment（gcs-security-assessment）：バケットのアクセス制御、ストレージのセキュリティ態勢、または SAIF 準拠を監査する際に有効化します。
   • NotebookLM Auth（notebooklm-auth）：NotebookLM MCP の Cookie または認証エラーを診断または解決する際に有効化します。

---

ワークフロー フェーズ 4：移植性と skills.json の全件管理

見つけやすさを最大限に高め、簡単に切り替えられるよう、skills.json は除外項目の一部リストではなく、インストール済みスキルすべてを対象とする明示的な全件管理パネルとして扱います。

Antigravity の skills.json の仕組み

• 場所：~/.gemini/config/skills.json（またはワークスペースの .agents/skills.json）。
• インストール済み・除外：exclude 配列内の通常の文字列（例："alloydb-basics"）。完全一致すると true と評価され、スキルはレベル 1 のプロンプト読み込みから除外されます。
• インストール済み・非アクティブ（検出可能）：exclude 配列内の // プレフィックス（例："//bigquery-sql"）。// プレフィックスにより完全一致が成立しないため（exclude.includes("bigquery-sql") は false と評価されます）、ローダーはそのスキルを検出可能として扱います（フロントマターが自動的にレベル 1 のプロンプトコンテキストに読み込まれます）。

照合と自動同期の手順

organise-agent-skills を実行する際は、次の手順に従います。

1. 不足しているスキルの自動登録：ディスク上に存在し、skills.json にないスキルフォルダーを追加します。新たに登録するスキルは、ユーザーの好みまたはトークン予算の方針に応じて、検出可能（"//skill-name"）または除外（"skill-name"）に設定します。
2. 孤立した項目の削除：対応するディレクトリがディスク上に存在しなくなった項目を skills.json から削除します。
3. アルファベット順に並べ替え：スキャンと差分比較を明瞭で予測しやすい状態に保つため、exclude 配列をアルファベット順に並べます。

skills.json の例：

{
  "exclude": [
    "accidental-data-loss-prevention", // INSTALLED AND EXCLUDED (no // prefix)
    "//agent-aware-cli",               // INSTALLED AND INACTIVE / DISCOVERABLE (// prefix workaround)
    "//using-agent-skills",            // INSTALLED AND INACTIVE / DISCOVERABLE (Master Meta-Skill)
    "spec-driven-development"          // INSTALLED AND EXCLUDED (Sub-skill activated on-demand)
  ]
}

移植性に関する注意事項

• skills.json は、Antigravity 環境におけるネイティブの除外メカニズムです。
• その他のエージェントフレームワーク（例：Claude Code、Cursor、Windsurf）では、ワークスペースの .agents/ 境界またはツール設定ファイルを通じてスキルの除外を管理します。メタスキルによる無効化と、必要に応じたファイル読み取りは、すべての LLM エージェントで完全に移植可能です。

---

ワークフローのフェーズ 5：ユーザーへの回答とドキュメントの更新

1. 実行前の提案： 監査結果、重複スキルの内訳、提案するアクションを、次の概要提案表とともにユーザーに提示します。

   指標	最適化前の基準値	最適化後の提案値	差分
   インストール済みスキルディレクトリ	N	M	-X
   インストール済みかつ検出可能なスキル	N	M	-X
   インストール済みかつ除外されたスキル	N	M	+X
   プロンプトのトークンオーバーヘッド	約Aトークン	約Bトークン	-Cトークン

   ファイルの削除や設定の変更を行う前に、ユーザーに明示的な確認を求めます。

2. 実行後の概要表： 承認を得て実行したら、正確な差分を示す最終指標表と、実施内容の明確な内訳を提示します。

   • インストール済みかつ検出可能なスキル：フロントマターがレベル 1 のプロンプトコンテキストに事前読み込みされるスキルです。
   • インストール済みかつ除外されたサブスキル：親メタスキルによって必要に応じて読み込まれ、アクティブ化されるスキルです。
   • インストール済みかつ除外されたオンデマンドスキル：GEMINI.md / AGENTS.md のルールを通じてアクティブ化されるスキルです。
   • インストール済みかつ除外されたドメインスキル：明示的にアクティブ化されるまで除外状態に保たれる、ニッチな専門スキルです。
   • 削除済み／廃止済みのスキル：古くなったスキルや重複したスキルで、ディスクから削除されたものです。

3. ドキュメントの更新： アクティブなスキルプロファイルとメタスキルの階層を記載するため、プロジェクトの README.md は必ず更新します。