---
title: "Skills 與漸進載入"
description: "基於官方 Skills 文件解釋 Antigravity Skill 的目錄結構、SKILL.md、description、workspace/global scope 和 progressive disclosure。"
verifiedAt: "2026-05-06"
---

Antigravity Skills 是擴充套件 agent 能力的開放標準。官方文件把 skill 定義為一個包含 `SKILL.md` 的資料夾，裡面寫著 agent 在特定任務中應該遵循的說明。

Skill 和 Rule、Workflow 最大的區別是：Skill 可以攜帶說明、最佳實踐、指令碼、示例和資源，並且按需載入。它適合“某類專業任務”，不適合普通一句提示詞。

> [!NOTE]
> **閱讀目標**：讀完本章，你應該能建立一個最小 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. 最小目錄結構

官方給出的最小結構是：

```text
.agents/skills/
└── my-skill/
    └── SKILL.md
```

`SKILL.md` 是唯一必需檔案，但可以擴充套件：

```text
.agents/skills/my-skill/
├── SKILL.md
├── scripts/
├── examples/
└── resources/
```

官方說明 agent 可以在執行 skill 時讀取這些檔案。

## 4. SKILL.md frontmatter

官方文件要求 `SKILL.md` 頂部有 YAML frontmatter。

```markdown
---
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 的關鍵資訊 |

> [!IMPORTANT]
> description 決定觸發質量。寫得太泛，agent 容易誤用；寫得太窄，agent 可能想不到載入。

## 5. Progressive disclosure

官方文件說明 Skills 遵循 progressive disclosure：

1. Conversation 開始時，agent 看到可用 skills 的 name 和 description。
2. 如果某個 skill 看起來和任務相關，agent 才讀取完整 `SKILL.md`。
3. agent 按 skill 說明執行任務。

```mermaid
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：

```text
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” 更好，因為它明確了任務、檢查維度和觸發場景。

<details>
<summary>深讀：Skill、Rule、Workflow 怎麼分工</summary>

Rule 是長期約束，Workflow 是可觸發步驟，Skill 是帶知識和資源的能力包。

如果一句話每次都要遵守，寫 Rule。如果一串步驟經常重複，寫 Workflow。如果這個任務需要專門方法、檢查清單、指令碼、模板、示例或參考資料，寫 Skill。

不要為了顯得高階把所有東西都做成 Skill。Skill 越多，description 路由越重要，維護成本也越高。
</details>

## 本章自檢

完成本章後，用這 3 個問題檢查自己是否真正理解：

1. `SKILL.md` 裡哪個 frontmatter 欄位決定 agent 是否會載入 Skill？
2. Workspace skill 和 global skill 分別適合什麼場景？
3. 為什麼複雜 Skill 應該包含 decision tree 或指令碼 `--help` 路徑？

透過標準：你能寫出一個最小 Skill 目錄，並用一句清晰 description 說明它什麼時候應該被觸發。

## 官方來源

- [Google Antigravity Skills](https://antigravity.google/docs/skills) —— 官方說明 Skills 定義、目錄位置、`SKILL.md`、frontmatter、progressive disclosure 和最佳實踐。
- [Agent Skills Open Standard](https://agentskills.io/home) —— 官方文件引用的 Agent Skills 開放標準入口。

## 接下來去哪

<Cards>
  <Card title="Rules 與 Workflows" description="回到長期約束和可觸發流程，判斷哪些內容不應該做成 Skill。" href="/zh-Hant/docs/antigravity/official/04-rules-workflows-skills/00-rules-workflows" />
  <Card title="MCP、許可權與安全" description="Skill 如果帶指令碼和資源，下一步必須理解工具和許可權邊界。" href="/zh-Hant/docs/antigravity/official/05-mcp-permissions-security" />
</Cards>
