[Google AI Pro・Antigravity目線] ちょっとしたPC作業でSKILLSを活用
— 段階的開示と知識の蓄え方・SKILL.mdの書き方

1. プログレッシブ・ディスクロージャー（段階的開示）とは

プログレッシブ・ディスクロージャーは、「必要なタイミングで必要な情報だけを提示する」という UX・情報設計の考え方です。いっぺんに全部見せず、基本から詳細へ段階的に開示することで、認知的負荷が減り、初心者も上級者も使いやすくなります。

Antigravity の公式ドキュメント（Skills）では、スキルはこの考え方に沿って参照されると説明されています。会話開始時、AI は次の3段階で情報に触れます。

1. Discovery（発見）：使えるスキル一覧と、各スキルの名前・説明（description）だけを見る。
2. Activation（有効化）：今のタスクに関係ありそうなスキルだけ、その SKILL.md の全文を読む。
3. Execution（実行）：実際の作業に合わせて、そのスキルの resources/ など必要なファイルを参照する。

過程のイメージ

※ ページ読み込み時に、流れに沿って順に表示されます。

最初から全部読まないので、トークンを節約できるうえ、AI が「今何に集中すべきか」を保ちやすくなります。
知識をたくさん蓄えても、段階的に開示される設計だからこそ使いこなせる、というイメージです。

2. どういう風に知識を蓄えるか

「調べたこと」「決めたルール」「よく使う手順」を、テーマやタスクごとに分けて蓄えると扱いやすいです。

例えば次のようなスキルに分けると、AI が「いつそのスキルを使うか」を description から判断しやすくなります。

• このワークスペースのルール・メモ
• 〇〇のAPIのまとめ
• 問い合わせテンプレ など

習慣のコツは、その場限りで終わらせず「あとで使い回す」前提でメモすること。一度調べた内容を「誰が読んでも分かるように」短くまとめておくと、同じ質問を何度もする手間が減ります。

3. どういう形で保存するのがいいか

保存形式は Markdown（.md）で resources/ に置くのが基本です。

MD 以外は大丈夫か？
公式では resources/ は「Templates and other assets（テンプレートやその他のアセット）」とだけ書かれており、拡張子は .md に限定されていません。オープン標準（agentskills.io）では、references/（ドキュメント）や assets/（データファイル・画像・テンプレート）が例に挙がっており、.md 以外のテキスト（.txt、.json など）やデータ・画像を置く想定もあります。Antigravity の resources/ は、この役割を一つのフォルダ名で提供しているイメージです。

一方で、エージェントが「内容を読み取って利用する」のは主にテキストが前提です。確実に扱いやすいのは .md や .txt などのテキスト形式で、画像やバイナリは実装依存のため、利用する場合は公式ドキュメントや実際の挙動で確認することをおすすめします。

1ファイルに全部詰め込むより、トピックごとにファイルを分けると、AI が「今必要なページ」だけを参照しやすくなります（プログレッシブ・ディスクロージャーと相性が良いです）。

ファイル名は内容が推測できるようにしておくとよいです（例：api-basics.md、rules.md）。SKILL.md の本文で「〇〇については resources/△△.md を参照する」と書いておくと、AI が迷いにくくなります。

Antigravity では作業の単位がワークスペース（いま開いているフォルダ）です。スキルを置く場所は次の2通りで、用途に応じて選びます。

実例に入る前に、何をするか簡単にまとめます。Google AI Pro プランで Antigravity を利用し、SKILLS 機能を使ってサンプルスキルを作っていきます。以下、実例1・実例2の順で進めます。

実例1：メモのフォーマットだけを用意したスキル

ワークスペース内に .agent/skills/sample-memo/ を用意し、SKILL.md と resources/format.md（メモのフォーマット例）だけを入れた状態で試しました。
図1〜図4で、フォルダ構成・資料の内容・SKILL.md・実行時の流れを示します。

結果：メモの整形（日付・見出し付き）は問題なくできました。
一方で、「どこに・どう保存するか」がスキルに書かれていなかったため、AI が「ファイル名を教えてください」とユーザーに聞く動きになりました。保存まで任せたい場合は、保存の手順をスキル側に含める必要があることが分かります。

図1：ワークスペース（このプロジェクト専用）のフォルダ構成

図2：資料（蓄えた情報）の例 — resources 内の .md

図3：重要な MD ファイル — SKILL.md（指示と構造）

図4：実行の流れ（実例1の状態）

実例2：実例1で足りなかった「保存の指示」を資料で追加したスキル

実例1とのつながり：
実例1では保存の手順がスキルに含まれておらず、AI が都度ユーザーにファイル名を聞く形になっていました。そこで、足りなかった「保存の指示」を resources/save-instructions.md として追加し、SKILL.md から参照する形にしたのが実例2です。
結果、ファイル名の有無に応じて「聞く」動き、または指定ファイルへ保存まで実行する動きになりました。

実例2では resources/save-instructions.md に「いつ保存するか」「ファイル名の有無によるやり方」「保存先」を記載し、SKILL.md の「保存について」から参照するようにしました。
図5がディレクトリ構成、図6が処理の流れです。

図5：保存資料を追加したときのディレクトリ構成

図6：保存資料を追加したときの処理の流れ

※ 同じフォーマットでメモを保存する PowerShell スクリプト（Save-Memo.ps1）も同梱しています。詳しくは後述の解説：PowerShell でメモ保存を参照。

実際に使用したスキルファイルの内容

実例1・実例2で使ったスキルファイル（SKILL.md・format.md・save-instructions.md）の全文です。各ブロック右上の Copy でコピーできます。

SKILL.md

---
name: sample-memo
description: Formats and saves short memos with date and title. Use when the user wants to jot down a memo, save a quick note, or says "メモを残して" or "今日のメモ".
---

# サンプルメモスキル

ユーザーが短いメモを残したいときに、日付と見出しをつけて整理します。

## いつ使うか

- 「メモを残して」「今日のメモ」「覚えておきたい」などと言ったとき
- 短いメモやリマインダーを記録したいとき

## やり方

1. メモの内容を聞く（またはユーザーが書いた内容を受け取る）
2. 当日の日付（YYYY-MM-DD）と、内容から分かる短い見出しをつける
3. 次の形式で返す：
   - 見出し（1行）
   - 日付
   - 本文（ユーザーのメモ）

詳細なフォーマット例は `resources/format.md` を参照してください。

## 保存について

メモをファイルに保存する手順は `resources/save-instructions.md` を参照してください。

## 注意

これはサンプル用のスキルです。必要に応じて上記の資料（format.md・save-instructions.md）に従ってください。

resources/format.md

# メモのフォーマット例

## 出力例

```
【買い物リスト】
2026-02-19
- 牛乳
- 電池
```

```
【会議メモ】
2026-02-19
〇〇について決定。次回は来週確認。
```

見出しは [ ] で囲むか、短いタイトルにします。日付は ISO 形式（YYYY-MM-DD）で統一します。

resources/save-instructions.md

# メモの保存手順

生成したメモをファイルに保存するときの指示です。

## いつ保存するか

- ユーザーが「保存して」「ファイルに残して」などと言ったとき
- ユーザーが最初から「〇〇.md に保存して」とファイル名を指定したとき
- メモを返したあと、保存の希望がなければ「このメモをファイルに保存しますか？」と聞く

## やり方

1. **ファイル名が指定されている場合**
   ユーザーが「memo.md に保存して」などと言っていれば、そのファイル名でワークスペース内の適切な場所に書き出す。

2. **ファイル名が指定されていない場合**
   「このメモをファイルに保存しますか？ 保存する場合はファイル名（例: memo.md）を教えてください」と返す。ユーザーがファイル名を答えたら、その名前で保存する。

3. **保存先**
   ワークスペース（いま開いているフォルダ）内。ユーザーがパスを指定していればそれに従う。

## 注意

- 上書きする場合は、既存ファイルがあることをユーザーに伝えてから行うか、確認する。
- これはサンプル用のスキルです。

4. SKILL.md の書き方（MDファイル）

SKILL.md は「そのスキルをいつ・どう使うか」を書くメインの指示書です。必須なのは次の2点です。

① 先頭の YAML フロントマター

• name：スキルの識別名（省略時はフォルダ名）。小文字・ハイフンが無難。
• description：必須。そのスキルが何をして、いつ使うかを、三人称で具体的に書く。AI は会話開始時にこの説明だけを見てスキルを選ぶため、キーワードを入れておくと選ばれやすくなります。

description の例：
良い例は「Reviews code changes for bugs, style issues, and best practices. Use when reviewing PRs or checking code quality.」のように具体的に書くこと。
避けたいのは「This skill helps you review code.」のように短く抽象的すぎる説明で、AI が判断しづらくなります。

② 本文（Markdown）

• いつ使うか：どのような質問・タスクのときにこのスキルを適用するか。
• 手順・チェックリスト：ステップや確認すべき項目。
• 参照先：必要なら「〇〇については resources/△△.md を読む」と明記。

本文は自然言語で書いてかまいませんが、見出し（##）・番号リスト・箇条書きで構造化しておくと、AI が把握しやすくなります（図2・図3を参考にしてください）。
複雑なスキルでは「状況に応じてどれを選ぶか」の判断の分岐（決定木）を書いておくと、AI が迷いにくくなります。

解説：PowerShell でメモ保存

「PowerShell でゴリゴリに責めたい人」向けに、同じようなことをスクリプトでもできます。Shell で同じフォーマットのメモを吐くだけなら、記事同梱の Save-Memo.ps1 で実現できます（Author: MidoriPhotoArt）。

入力はテキスト1つだけ。.\Save-Memo.ps1 "牛乳, 電池" のように渡すと、ファイル名は memo_日付_時刻.txt で自動作成され、実例1・2と同じ [見出し] ＋ 日付 ＋ 本文 の形で UTF-8 保存されます。1行だけなら見出しは「メモ」、改行を含めると1行目が見出し・2行目以降が本文です。

図7：PowerShell での実行例

SKILLS は「自然言語で頼むと AI がフォーマットと保存までやってくれる」のが強み。スクリプトで十分な方はこちらでゴリゴリどうぞ、という感じです。

豆知識：スキルを追加・変更したら会話をやり直す

Antigravity はコンテキスト（会話）を開始したときの最初の一度だけ、使えるスキル一覧（name と description）を読みにいきます。

そのため、会話の途中でスキルを追加したり SKILL.md を書き換えたりしても、その会話では反映されません。新しいスキルや変更した内容を試すときは、新しいチャットを開いてから話すと確実です。

プログレッシブ・ディスクロージャーの「まず一覧だけ見る」という動きの裏側だと覚えておくと、挙動に納得しやすいです。（根拠：Antigravity Documentation — Skills で会話開始時にスキルを参照する流れとして説明されています。下記「データソース・参考リンク」も参照。）

まとめ

SKILLS を深めるポイントは次の3つです。

1. プログレッシブ・ディスクロージャーの考え方（必要なときだけ必要な情報を開示）を理解する。
2. 知識をテーマ・タスクごとに分けて .md で蓄える。
3. SKILL.md では YAML の description を三人称で具体的に書き、本文で「いつ使うか・手順・参照先」を書く。

AI を仕事や生活でちょっと使ってみたい方は、1本のスキルから試して、少しずつ中身を増やしていくのがおすすめです。