Skills 與漸進載入
基於官方 Skills 文件解釋 Antigravity Skill 的目錄結構、SKILL.md、description、workspace/global scope 和 progressive disclosure。
Antigravity Skills 是擴充套件 agent 能力的開放標準。官方文件把 skill 定義為一個包含 SKILL.md 的資料夾，裡面寫著 agent 在特定任務中應該遵循的說明。
Skill 和 Rule、Workflow 最大的區別是：Skill 可以攜帶說明、最佳實踐、指令碼、示例和資源，並且按需載入。它適合“某類專業任務”，不適合普通一句提示詞。
閱讀目標：讀完本章，你應該能建立一個最小 Skill，並寫出能讓 agent 正確觸發的 description。
1. Skill 解決什麼問題
官方文件說明，Skills 是 reusable packages of knowledge，用來擴充套件 agent 能做什麼。每個 skill 可以包含：
- 特定任務的操作說明。
- 應遵循的最佳實踐和約定。
- 可選指令碼和資源。
適合做成 Skill：
| 任務 | 原因 |
|---|---|
| Code review | 有穩定檢查清單和反饋格式 |
| Unit test generation | 有語言、框架、目錄約定 |
| Release audit | 需要指令碼、清單、風險邊界 |
| Design screenshot review | 需要視覺標準和 viewport 規則 |
| Data migration | 需要步驟、指令碼和回復策略 |
不適合做成 Skill：
- 一次性任務。
- 很短的個人偏好。
- 單個 slash workflow 就能表達的流程。
- 沒有明確觸發場景的知識堆疊。
2. Workspace Skill 與 Global Skill
官方文件列出兩個 skill scope。
| 型別 | 路徑 | 適合 |
|---|---|---|
| Workspace skill | <workspace-root>/.agents/skills/<skill-folder>/ | 團隊專案專屬部署、測試、程式碼規範 |
| Global skill | ~/.gemini/antigravity/skills/<skill-folder>/ | 個人跨專案通用工具 |
官方也說明 Antigravity 預設 .agents/skills，並保留 .agent/skills 向後支援。
團隊專案優先 workspace skill，因為它能隨專案進入版本控制。個人跨專案工具才放 global skill。
3. 最小目錄結構
官方給出的最小結構是：
.agents/skills/
└── my-skill/
└── SKILL.mdSKILL.md 是唯一必需檔案，但可以擴充套件：
.agents/skills/my-skill/
├── SKILL.md
├── scripts/
├── examples/
└── resources/官方說明 agent 可以在執行 skill 時讀取這些檔案。
4. SKILL.md frontmatter
官方文件要求 SKILL.md 頂部有 YAML frontmatter。
---
name: my-skill
description: Helps with a specific task. Use when you need to do X or Y.
---
# My Skill
Detailed instructions for the agent go here.欄位重點：
| Field | Required | 說明 |
|---|---|---|
name | No | 唯一標識；沒有寫時預設使用資料夾名 |
description | Yes | agent 判斷是否使用 skill 的關鍵資訊 |
description 決定觸發質量。寫得太泛，agent 容易誤用；寫得太窄，agent 可能想不到載入。
5. Progressive disclosure
官方文件說明 Skills 遵循 progressive disclosure：
- Conversation 開始時，agent 看到可用 skills 的 name 和 description。
- 如果某個 skill 看起來和任務相關，agent 才讀取完整
SKILL.md。 - agent 按 skill 說明執行任務。
flowchart TD
Start["Conversation starts"] --> List["Agent sees skill names + descriptions"]
List --> Match{"Description matches task"}
Match -->|yes| Read["Read SKILL.md"]
Match -->|no| Ignore["Do not load full skill"]
Read --> Execute["Follow instructions / scripts / resources"]這解釋了為什麼 Skill 不應該把 description 寫成廣告語。它是路由條件，不是封面文案。
6. 官方最佳實踐怎麼落地
官方 Skills 文件給出幾條關鍵實踐：
| 官方建議 | 中文落地 |
|---|---|
| Keep skills focused | 一個 skill 做一類任務，不做萬能包 |
| Write clear descriptions | description 用第三人稱，寫清何時使用 |
| Use scripts as black boxes | 有指令碼時先讓 agent 跑 --help，不要先讀全部原始碼 |
| Include decision trees | 複雜任務加決策樹，幫 agent 選路徑 |
示例 description：
Reviews local code changes for correctness, edge cases, project conventions, tests, and release risk. Use before accepting implementation diffs or preparing a pull request.這個描述比 “A powerful code review skill” 更好，因為它明確了任務、檢查維度和觸發場景。
深讀：Skill、Rule、Workflow 怎麼分工
Rule 是長期約束，Workflow 是可觸發步驟，Skill 是帶知識和資源的能力包。
如果一句話每次都要遵守，寫 Rule。如果一串步驟經常重複，寫 Workflow。如果這個任務需要專門方法、檢查清單、指令碼、模板、示例或參考資料，寫 Skill。
不要為了顯得高階把所有東西都做成 Skill。Skill 越多，description 路由越重要，維護成本也越高。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
SKILL.md裡哪個 frontmatter 欄位決定 agent 是否會載入 Skill？- Workspace skill 和 global skill 分別適合什麼場景？
- 為什麼複雜 Skill 應該包含 decision tree 或指令碼
--help路徑？
透過標準：你能寫出一個最小 Skill 目錄，並用一句清晰 description 說明它什麼時候應該被觸發。
官方來源
- Google Antigravity Skills —— 官方說明 Skills 定義、目錄位置、
SKILL.md、frontmatter、progressive disclosure 和最佳實踐。 - Agent Skills Open Standard —— 官方文件引用的 Agent Skills 開放標準入口。