Google Antigravity IDE 教學 (二)：Agent Skills 實戰 - 從概念到進階應用

概念：什麼是 Agent Skill？

不只是一堆 Prompt，而是一份「可執行的結構化知識庫」。

Agent Skill 本質上是一份「操作手冊 SOP」，讓 AI 在遇到特定問題或情境時，能夠自動感知並知道該如何處理。

Agent Skills 如何運作？— Antigravity 環境下的協作模式

要讓這些強大的 Skills 發揮作用，我們需要一個 agentic development platform。以 Antigravity 來說，Agent 會在工作開始時看到可用 skill 的名稱與 description；如果某個 skill 看起來符合任務，它才會讀取完整 SKILL.md 內容並依照指示執行。

模型名稱、額度與可用方案會隨官方更新調整，因此本篇不再綁定特定模型或價格方案。重點是學會把團隊 SOP、檢查清單、腳本與範例包成可重複使用的 Skill。

Skill 結構解剖

官方文件指出，Skill 是一個包含 SKILL.md 的資料夾；除了必要的主文件，也可以視需要加入 scripts、examples 與 resources：

解釋運作流程

當你在 Antigravity 中與 AI 互動時，Agent Skills 的運作流程如下：

1. 使用者下達指令：你用自然語言輸入一個指令，例如：「幫我整理一下下載文件夾」。
2. Agent 判斷任務類型：Agent 會根據對話內容與可用 Skills 的 description 判斷是否需要套用某個技能。
3. 讀取 SKILL.md：當 skill 看起來相關時，Agent 會讀取完整 SKILL.md，再依照其中的步驟、限制與輸出格式工作。
4. 按需使用資源：如果 skill 內有 scripts、examples 或 resources，Agent 可依任務需要讀取或執行，不必把所有知識一次塞進對話。

關鍵設計原則

Agent Skill 背後的設計理念與運作機制帶來了四大核心優勢：

步驟一：Skill 的安裝位置

官方目前建議把 workspace-level Agent Skills 放在專案根目錄下的 .agents/skills。Antigravity IDE 與 Antigravity CLI 會依據這個目錄載入 workspace skills。

當您想要「安裝」一個新技能時，只需要將該技能的資料夾放到 .agents/skills。每個 skill 都應該是一個獨立資料夾，且資料夾內必須有 SKILL.md。

遷移提醒：舊版 .agent/skills 仍可能被支援，但新專案建議改用 .agents/skills；Antigravity CLI 也把 Gemini CLI 舊有的 .gemini/skills workspace skills 遷移到 .agents/skills。

Skill 安裝位置對照

步驟二：解剖 SKILL.md

讓我們來看一個最簡單的 SKILL.md 範例。假設我們要教 Agent 如何生成「每日工作日報」。

---
description: 當使用者要求總結今日工作、撰寫日報，或整理今天完成事項時使用此技能。
---

# Generate Daily Report

## 目的
根據工作日誌與當前的任務狀態，生成一份 Markdown 格式的日報。

## 執行步驟
1. 讀取今天工作紀錄 task.md。
2. 檢查 task.md 的各項任務完成狀態。
3. 彙整成以下格式：
   - 完成事項
   - 工時占比
   - 遭遇困難
   - 未來計畫

關鍵點解析：

• description： 這是最重要的觸發提示。請寫清楚「什麼情境下使用此技能」，避免太廣或太模糊。
• Markdown 主體： 用標題、步驟、限制與輸出格式告訴 Agent 實際該怎麼做。
• 按需資源： 複雜技能可以在 resources/ 放政策、模板或 glossary，在 scripts/ 放可重複執行的工具。

小試身手

工程師術語翻譯機 (Jargon Simplifier)

在進入更複雜的應用前，我們先看一個 PM 必備的利器。這是一個能把「工程師的報錯訊息」翻譯成「人話」的迷你 Skill：

---
description: 當使用者貼上看不懂的 error log、HTTP 錯誤、工程師術語，並要求用非技術人員能理解的方式解釋時使用此技能。
---
# Role
你是一位擅長溝通的技術型 PM，負責向非技術人員解釋系統狀況。

# Instructions
1. 讀取使用者提供的錯誤訊息 (e.g., "502 Bad Gateway", "CORS Error")。
2. 用最白話的比喻解釋發生了什麼事 (例如：用「餐廳廚房忙不過來」解釋 502)。
3. 提供一個「建議行動」(例如：「請工程師檢查 Nginx 設定」)。

就是這麼簡單！存檔後，下次當你看到一堆紅字報錯，只要貼給 Agent，它就會告訴你發生了什麼事，讓你不再被術語嚇到。

Zero Code: 讓 Agent 幫你寫 Skill

覺得寫 YAML 和 Markdown 太麻煩？其實你可以直接用講的！

試著在 Agent Manager 中輸入：

請幫我建立一個新的 Agent Skill。
功能是：當我貼上錯誤訊息時，請扮演技術 PM，用非技術人員聽得懂的比喻來解釋它。

Agent 會自動生成符合格式的 SKILL.md，並協助放到 .agents/skills/jargon-simplifier/。這就是 Agentic Coding 的魅力！

步驟三：驗證技能是否生效

在測試之前，請確保您已完成技能安裝。對於非工程師，我們建議採用以下兩種方式之一：

方法一 (推薦)： 參考上方的 Zero Code 區塊，直接請 Agent 幫您建立。

方法二 (手動)：

1. 在 IDE 左側檔案列表找到或建立 .agents/skills 資料夾。
2. 按右鍵選擇 "New Folder"，命名為 jargon-simplifier。
3. 在該資料夾內建立新檔案 SKILL.md。
4. 將上方的 Markdown 內容複製貼上並儲存。

安裝完成後，我們可以來測試看看：

1. 在 Agent Manager 或 Editor 的聊天輸入框中提出任務。
2. 隨意貼上一段報錯訊息，例如：502 Bad Gateway 或 CORS policy blocked。
3. 觀察 Agent 是否依照 Skill 的角色、語氣與輸出格式回答。實際 UI 是否顯示 skill 名稱，請以目前版本為準。
4. Agent 隨後會用「餐廳廚房」等淺顯易懂的比喻來解釋這個錯誤，這證明了它已成功掛載了這項技能。

進階挑戰：實戰規格書架構師 (Spec Architect)

既然您已經學會了基礎，現在讓我們來挑戰一個更複雜的真實案例：打造一個能幫 PM 自動撰寫 PRD 初稿的助手。

這次我們不再手把手教您建立資料夾，請試著運用剛剛學到的技巧 (Zero Code 或 手動建立)，安裝以下技能：

---
description: 當使用者要求整理會議記錄、需求筆記、客戶訪談，或撰寫產品規格書 PRD 時使用此技能。
---

# Role
你是一位擁有 10 年經驗的資深產品經理 (PM)，擅長釐清需求邊界並撰寫 User Stories。

# Instructions
1. **Analyze (分析)**: 
   - 讀取使用者提供的輸入內容 (會議筆記、對話記錄)。
   - 識別核心功能 (Core Features) 與使用情境 (Scenarios)。

2. **Structure (結構化)**:
   - 產生一份符合 Markdown 格式的 PRD，必須包含：
     - **Background**: 為什麼要做這個？解決什麼問題？
     - **User Stories**: 使用 "As a... I want to... So that..." 格式。
     - **Acceptance Criteria**: 使用 Gherkin (Given/When/Then) 語法。

3. **Tone (語氣)**:
   - 保持專業、精簡、無廢話。

試煉任務： 安裝完成後，請對 Agent 說：

「把這份會議記錄整理成 PRD。內容是關於一個新的『深色模式』功能...」

如果 Agent 能穩定吐出結構完整的 PRD，就代表這個 Skill 已經能把團隊規格書流程轉成可重複使用的工作規範。