Google Antigravity 現在正式支援 Agent Skills，等於把「客製化工作流」這件事，直接長在 Agent 裡。對於常用 Antigravity 處理專案、寫程式或自動化日常工作的開發者來說，這是一個非常關鍵的升級。

下面就用實際使用心得的角度，把 Agent Skills 的概念、結構與最佳實踐一次整理好，讓你可以馬上在自己的 Workspace 裡開始動手做。

什麼是 Agent Skills？
簡單說，Skills 就是「可重複使用的知識模組」，專門用來擴充 Agent 的能力。每一個 Skill 都是一個資料夾，裡面至少要有一個 SKILL.md，負責告訴 Agent：

適合處理哪一種任務
這類任務該採取什麼步驟
有哪些最佳實踐與慣例要遵守
有沒有額外可以搭配使用的 scripts 或 resources
在對話開始時，Agent 會先看到一個 Skills 列表，只包含名稱與描述。當覺得有符合你的需求時，它才會進一步打開那個 Skill 的 SKILL.md，照裡面的指示來協助你完成工作。

Skills 放在哪裡？
Antigravity 支援兩種 Skills 作用範圍：Workspace-specific 和 Global。

1. Workspace Skills（專案專用）
路徑長這樣：

text
/.agent/skills//
適合放：

某個專案專用的部署流程
團隊內約定好的測試規範
特定 repo 的 code review 樣板
也就是：只跟這個 Workspace 有關的東西，就集中在這裡。

2. Global Skills（全域共用）
路徑在使用者家目錄下：

text
~/.gemini/antigravity/skills//
適合放：

個人常用工具（例如：產生 commit message、整理 meeting notes）
多個專案都會用到的通用腳本或慣例
一般性的程式碼檢查、文件撰寫規則
這類 Skills 一旦寫好，就可以在你所有 Workspace 裡被 Agent 看見並使用。

如何建立一個 Skill？
步驟很精簡：

在指定的 skills 目錄裡建立一個資料夾
在該資料夾裡新增一個 SKILL.md 檔案
範例結構：

text
.agent/skills/
└── my-skill/
└── SKILL.md
每一個 Skill 都必須有一個 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.

## When to use this skill

– Use this when…
– This is helpful for…

## How to use it

Step-by-step guidance, conventions, and patterns the agent should follow.
上半部的 frontmatter 是給 Antigravity 系統看的；下面的內容則是給 Agent 在真正執行任務時參考的「操作手冊」。

Frontmatter 欄位說明
在 SKILL.md 的 YAML frontmatter 裡，目前有兩個重要欄位：

name（非必填）
Skill 的唯一識別名稱
建議使用全小寫、空白改用 hyphen（例：code-review, python-unit-tests）
若沒填，會自動以資料夾名稱當作 name
description（必填）
一句話說清楚這個 Skill 的用途與適用情境
這段文字會出現在 Agent 的 Skills 列表中，決定它要不要選用這個 Skill
建議用第三人稱，並加入關鍵字，讓 Agent 比較容易判斷匹配度
例如：
Generates unit tests for Python code using pytest conventions.
Summarizes technical design documents into executive-friendly overviews.
在實際使用上，description 的品質會直接影響 Agent 是否「看得懂」何時該用你的 Skill，這是最值得花時間打磨的地方。

Skill 資料夾結構建議
雖然 SKILL.md 是唯一必備的檔案，但實務上你可以擴充更多內容，讓 Skill 更像一個完整的工作模組。典型結構如下：

text
.agent/skills/my-skill/
├── SKILL.md # 主說明與指令 (必須)
├── scripts/ # 輔助腳本 (選用)
├── examples/ # 範例實作或輸出 (選用)
└── resources/ # 樣板、設定檔等資源 (選用)
Agent 在遵循 Skill 的指示時，可以讀取這些檔案，比如：

scripts/ 裡的 CLI 工具
examples/ 裡的範例輸入與輸出
resources/ 裡的文件模板、標準說明、設定樣板
這些內容能幫你把「如何做事」的 know-how，完整封裝在 Skill 裡，不再散落在文件或口頭共識中。

Agent 如何使用 Skills？
Antigravity 的 Skills 遵循「漸進式揭露」（progressive disclosure）的模式，大致分成三個階段：

Discovery（發現）
對話開始時，Agent 會先取得一份 Skills 清單
每個 Skill 只有 name 與 description
Agent 會用這些描述來判斷當前任務需要哪些 Skills
Activation（啟用）
一旦某個 Skill 看起來與你的需求有關，Agent 會讀取該 Skill 的 SKILL.md 全文
理解裡面定義的流程、規範與注意事項
Execution（執行）
在任務進行期間，Agent 會根據 Skill 裡的指示，來決定具體步驟與輸出格式
也可以依照指示使用 scripts 或 resources
一般情況下，你不需要明確告訴 Agent「請使用某某 Skill」，它會根據上下文自行判斷。不過如果你很希望某個 Skill 一定要被套用，也可以在對話中直接提到 Skill 的名稱，來提高被使用的機率。

撰寫 Skills 的最佳實踐
1. 每個 Skill 專注一件事
避免寫成「萬用 Skill」。比較好的做法是：

一個 Skill 負責 code review
一個 Skill 負責 unit tests 產生
一個 Skill 負責部署流程檢查
這樣 Agent 比較容易判斷「何時」該用哪一個 Skill，維護起來也更清楚。

2. 把 description 寫得具體又可辨識
想像 Agent 只看得到一行 description，它就得決定要不要打開這個 Skill。
所以 description 需要：

說清楚做什麼事：Reviews code changes for bugs, style issues, and best practices.
說清楚什麼情境適用：Use when reviewing PRs or checking code quality.
包含關鍵字：程式語言、框架、工具名稱、作業型態（review, generate, summarize, test…）
描述越明確，Agent 越懂得何時可以靠這個 Skill 幫你節省時間。

3. 把 scripts 當作黑盒子使用
如果 Skill 內有 scripts，例如：

text
scripts/
└── run-tests.sh
建議在 SKILL.md 裡明確指示 Agent：

先用 –help 來了解用法，而不是讀完整原始碼

像這樣的說明可以寫進 Skill：

When using scripts in the scripts/ directory, prefer running them with –help to understand usage instead of reading their full source code.

這可以避免把大量 script 原始碼塞進 Agent 的上下文，保留更多空間給真正的問題和輸出。

4. 為複雜任務寫「決策樹」
如果 Skill 本身要處理的範圍比較廣，例如「後端服務的 code review」，就很適合在 SKILL.md 裡加入 Decision Tree，例如：

如果變更包含資料庫 migration → 優先檢查 schema 變更與相容性
如果有對外 API 介面調整 → 檢查版本控管與文件更新
如果變更內容集中在效能關鍵路徑 → 加強檢查複雜度與 caching 策略
這類決策邏輯寫清楚之後，Agent 在不同情境下就能走對分支，不會每次都給一樣的制式回應。

範例：Code Review Skill
底下是一個相對精簡、但很實用的 Skill 範例，專門針對程式碼審查：

markdown
—
name: code-review
description: Reviews code changes for bugs, style issues, and best practices. Use when reviewing PRs or checking code quality.
—

# Code Review Skill

When reviewing code, follow these steps:

## Review checklist

1. **Correctness**: Does the code do what it’s supposed to?
2. **Edge cases**: Are error conditions handled?
3. **Style**: Does it follow project conventions?
4. **Performance**: Are there obvious inefficiencies?

## How to provide feedback

– Be specific about what needs to change
– Explain why, not just what
– Suggest alternatives when possible
實際使用時，只要你的對話內容是在看 PR、檢查 diff 或要求 code review，Agent 就很有機會自動套用這個 Skill，並依照 checklist 逐點幫你檢查。

結語：把「團隊默契」變成可重用的 Skill
Antigravity 的 Agent Skills 本質上是一個把「經驗」與「流程」系統化的工具：

Workspace Skills：讓專案的獨特流程有固定的落腳處
Global Skills：把你個人的工作習慣，升級成隨處可用的標準工具
只要先從一個你每天都會重複做的任務開始，例如：

code review
撰寫技術文件
撰寫單元測試
部署前檢查清單
為它寫一個簡單的 Skill，把步驟、慣例和注意事項全部放進 SKILL.md，接下來就交給 Agent 幫你執行。當 Skills 慢慢累積起來，你會發現自己的 Antigravity Workspace，越來越像一個為自己量身打造的智慧開發環境。