組み込み Guide スキルを使い捨てにせず、設計資産として育てる

エージェントに同じ前提を毎回説明している、という感覚に心当たりはないでしょうか。プロジェクトのディレクトリ規約、コミットメッセージの書き方、レビューで必ず見る観点。会話を始めるたびにこれらを貼り付け直していると、本来集中したい作業の手前で時間が溶けていきます。

Antigravity v2.2.1 で組み込みの Guide スキルが入り、この繰り返しをスキルとして固定できるようになりました。ただ、ここで一度きりの便利機能として消費してしまうのか、それともチームと自分の知見を蓄積する場所として育てるのかで、半年後の効きが大きく変わってきます。

私自身、個人開発で複数のブログとアプリを並行して回しているので、エージェントに渡す前提知識は放っておくと際限なく増えていきます。Guide スキルをその場しのぎで書き捨てるたびに、似た内容を三度も四度も書き直していました。そこで運用の型を決めたところ、エージェントの初動が安定し、説明のやり直しがはっきり減りました。その型を共有します。

Guide スキルは「会話の外」に知識を逃がす仕組み

Guide スキルの本質は、会話コンテキストに毎回載せていた前提を、参照可能な外部知識として切り出すことにあります。プロンプトに直接書く方式と比べると、性質がかなり違います。

特に効くのが履歴です。「なぜこの規約にしたのか」をスキルの変更履歴に残しておくと、半年後の自分が同じ議論を蒸し返さずに済みます。私はこの一点だけでも Git 管理に乗せる価値があると考えています。

3層に分けて、スキルを肥大化させない

最初にやりがちな失敗が、1つのスキルにすべてを詰め込むことです。規約も手順もトラブル対処も全部入りにすると、エージェントが文脈に応じて必要な箇所を選べず、かえって精度が落ちます。

私はスキルを役割で3層に分けています。

第1層: 不変の前提（foundation）

プロジェクトの普遍的な約束事を置きます。変更頻度が低く、ほぼ全タスクで参照される内容です。

.antigravity/guides/
├── foundation/
│   ├── repo-conventions.md      # ディレクトリ・命名規約
│   ├── commit-style.md          # コミットメッセージの型
│   └── review-checklist.md      # レビュー必須観点

第2層: タスク種別ごとの手順（workflows）

「記事を1本追加する」「依存を更新する」のような、繰り返す作業の段取りです。手順そのものなので、ステップを番号で明示します。

├── workflows/
│   ├── add-article.md           # 記事追加の手順
│   ├── dependency-bump.md       # 依存更新と動作確認
│   └── release-checklist.md     # リリース前の確認項目

第3層: 落とし穴と対処（pitfalls）

過去に踏んだ罠を、症状と対処のペアで記録します。エージェントが似た状況に入ったとき、ここを参照させると同じ失敗を繰り返しません。

└── pitfalls/
    ├── edge-cache-stale.md      # キャッシュ起因の不整合
    └── i18n-count-mismatch.md   # 日英件数ずれの検出と修正

分割の目安は、1ファイル 200〜400 行です。これを超えたら、内部で扱っている関心事が複数あるサインなので、切り出しを検討します。逆に 50 行に満たないものは、関連スキルへの統合を考えます。