07 · Rules、Workflows、Skills 怎麼沉澱
Antigravity 長期使用的三層沉澱：Rules 管預設行為，Workflows 管按需流程，Skills 管可複用專業能力包。
Antigravity 用久以後，真正拉開差距的不是 prompt 寫得多長，而是你能不能把反覆出現的要求沉澱成 Rules、Workflows 和 Skills。否則每個任務都要從頭解釋一遍，agent 也會不斷重複犯同一類錯誤。
官方文件裡，Rules 是使用者手動定義的約束，Workflows 是一組可重複執行的步驟，Skills 是帶 SKILL.md 的能力包。三者都能影響 agent，但職責完全不同。
一句話分工：Rules 管“每次都該遵守什麼”，Workflows 管“我主動觸發什麼流程”，Skills 管“特定任務需要載入什麼專業知識和工具”。
閱讀目標：讀完本章，你應該能判斷一條經驗應該寫進 Rule、Workflow、Skill，還是繼續保留成普通 prompt。
1. 三者怎麼選
flowchart TD
Habit["一條經驗"] --> Always{"每次都需要?"}
Always -->|是| Rule["Rule"]
Always -->|否| Manual{"需要我手動觸發?"}
Manual -->|是| Workflow["Workflow"]
Manual -->|否| Rich{"需要指令碼/模板/參考資料?"}
Rich -->|是| Skill["Skill"]
Rich -->|否| Prompt["普通 prompt 即可"]判斷時先問三個問題：
- 是否每次都必須遵守？是就寫 Rule。
- 是否是一串可重複步驟？是就寫 Workflow。
- 是否需要指令碼、模板、示例或參考資料？是就寫 Skill。
不要把所有沉澱都做成 Skill。Skill 的維護成本最高，只有專業任務和可複用資源足夠多時才值得。
2. Rules：預設行為
Rules 適合寫專案長期約定。例如：
- 所有改動先讀本目錄規則。
- 修改前先給方案。
- UI 改動必須截圖。
- 禁止觸碰憑據檔案。
- 執行命令前說明目的。
- 大範圍改動先拆階段。
Rules 的風險是越寫越長。越長越容易稀釋重點。成熟規則應該短、具體、可執行。
官方 Rules 文件給了幾個關鍵事實：
| 規則項 | 官方路徑或限制 | 實操建議 |
|---|---|---|
| Global Rules | ~/.gemini/GEMINI.md | 放個人跨專案習慣 |
| Workspace Rules | <workspace-root>/.agents/rules/ | 放專案和團隊約定 |
| 單檔案限制 | 12,000 字元 | 只寫穩定約束，不寫百科 |
| 啟用方式 | Manual / Always On / Model Decision / Glob | 不是所有規則都設 Always On |
| 建立入口 | Editor 頂部 agent panel 的 ... 下拉 → Customizations → Rules → + Global / + Workspace | 團隊規範走 Workspace，個人習慣走 Global |
| 向後相容 | 預設 .agents/rules，仍相容舊路徑 .agent/rules | 新倉只用 .agents/rules |
Workspace rules 優先於口頭約定，因為它們能被版本控制、審查和團隊複用。Global rules 更適合個人表達風格、通用安全習慣，不適合承載某個專案的構建命令或部署流程。
3. Rule 啟用方式怎麼選
| 啟用方式 | 適合 | 不適合 |
|---|---|---|
| Always On | 安全紅線、專案硬約束 | 長篇背景資料 |
| Manual | 低頻但必須精確呼叫的規則 | 每次都要遵守的規範 |
| Model Decision | 邊界清楚、讓模型按描述判斷 | 描述模糊的規則 |
| Glob | 某類檔案專屬約定 | 跨全專案通用約束 |
例如：
Always On：禁止修改 .env、凭据目录和生产部署配置。
Glob：对 content/docs/**/*.mdx 应用教程页写作规范。
Manual：需要发布前复检时手动 @release-checklist。
Model Decision：当任务涉及 UI 改动时应用 UI 验收规则。Rule 還支援 @filename 引用檔案。相對路徑按 Rules 檔案所在位置解釋，絕對路徑先按真實路徑解析，不存在時再回退到 workspace。團隊規則裡不要引用個人本機私有絕對路徑，否則別人無法復現。
4. Workflows：按需流程
Workflows 適合儲存可重複觸發的流程。例如：
/ui-verify
- 启动本地服务
- 打开指定页面
- 检查 console
- desktop/mobile 截图
- 输出 walkthrough適合 workflow 的特點：
- 不是每個任務都要執行。
- 觸發時步驟比較固定。
- 不需要大型指令碼或大量參考檔案。
- 使用者希望用
/快速呼叫。
官方 Workflows 文件說明，workflow 儲存為 markdown 檔案，單檔案同樣限制在 12,000 字元以內，可透過 /workflow-name slash command 呼叫，也可以在一個 workflow 裡呼叫其他 workflows（例如 /workflow-1 內部呼叫 /workflow-2）。Workflow 同樣從 Editor agent panel 的 Customizations → Workflows → + Global / + Workspace 建立。適合這些場景：
| Workflow | 觸發目的 |
|---|---|
/ui-verify | UI 改動後跑瀏覽器驗收 |
/release-check | 釋出前做質量、構建、風險彙總 |
/pr-response | 按評論定位、修改、驗證、回覆 |
/docs-polish | 對教程頁做結構、來源、MDX 展示修正 |
不要把 workflow 寫成自由發揮。它應該包含輸入、步驟、停止點、驗收輸出。
走完一段任務後，可以直接讓 agent 幫你把對話變成 workflow（官方 Agent-Generated Workflows）。一段已經驗證過的真實操作歷史，比純憑空寫出來的 workflow 更可靠。
5. Skills：專業能力包
Skills 適合放“有觸發描述、有操作步驟、有指令碼或參考資料”的能力。比如：
- code-review
- ui-qa
- release-check
- docs-polish
- security-audit
一個 skill 不應該只是長規則。它應該包含：
| 部分 | 作用 |
|---|---|
name | 穩定標識 |
description | 決定何時載入 |
| instructions | 做事步驟 |
| scripts | 可執行檢查 |
| references | 模板、規範、樣例 |
| assets | 必要素材 |
官方 Skills 文件說明，Skill 是一個包含 SKILL.md 的資料夾，description 是 agent 決定是否載入 skill 的關鍵欄位；agent 先看到 name 和 description，相關時才讀取完整說明。這就是 progressive disclosure。
和 Rules 一樣，Skills 也有 workspace 和 global 兩個 scope，路徑分別在：
| Scope | 路徑 |
|---|---|
| Workspace（專案專屬） | <workspace-root>/.agents/skills/<skill-folder>/ |
| Global（個人跨專案） | ~/.gemini/antigravity/skills/<skill-folder>/ |
Antigravity 預設
.agents/skills，但仍相容舊路徑.agent/skills。新建 skill 一律用複數形式.agents/。
最小結構：
.agents/skills/
└── ui-qa/
└── SKILL.md更完整結構：
.agents/skills/ui-qa/
├── SKILL.md
├── scripts/
├── examples/
└── resources/SKILL.md 的 description 不要寫成廣告語，要寫成觸發條件（用第三人稱 + 關鍵詞，讓 agent 看一眼就知道什麼時候載入）：
---
name: ui-qa
description: Reviews local UI changes with viewport checks, console inspection, screenshots, and interaction walkthroughs. Use after frontend layout, component, or copy changes.
---Antigravity 的主推模型對中英文都有良好支援，description 可中可英；不確定時用英文 + 關鍵詞最穩，因為 agent 是基於關鍵詞匹配判斷 skill 是否相關的。
另外兩條值得記的官方 best practice：
- Keep skills focused：一個 skill 只做一件事，不要做"什麼都管"的大 skill。
- Use scripts as black boxes：如果 skill 帶指令碼，讓 agent 先
script --help而不是讀完整原始碼，能省下 agent 的 context 用在真正的任務上。
6. Global 還是 workspace
| 內容 | 放 global | 放 workspace |
|---|---|---|
| 個人表達偏好 | ✅ | |
| 公司專案規則 | ✅ | |
| 專案構建和驗收 SOP | ✅ | |
| 通用程式碼審查 skill | ✅ | 可按專案覆寫 |
| 產品專屬釋出流程 | ✅ |
商業專案優先 workspace scope。只有 workspace 內的規則和 skill 才能被團隊審計、版本化和複用。
如果是個人工具，例如通用 code review skill，可以放 global；如果涉及專案命令、私有部署、內容規範、截圖路徑、釋出賬號邊界，就應該放 workspace。
7. 從 prompt 進化到沉澱
一個成熟演進路徑：
- 第一次：手寫 prompt。
- 第二次：複製 prompt，刪改。
- 第三次：做成 workflow。
- 出現指令碼/模板/參考檔案：升級成 skill。
- 每次都必須遵守的部分：抽到 rule。
不要第一天就把所有東西做成 skill。先讓真實任務證明它值得沉澱。
8. 實戰模板
UI 驗收 workflow 可以這樣寫：
# UI Verify
1. 启动项目本地服务。
2. 打开用户指定页面。
3. 检查 console error。
4. 分别截 desktop 与 mobile。
5. 如果有交互，录制关键路径或写 walkthrough。
6. 输出改动文件、验证结果、未覆盖风险。後續如果要附帶 screenshot 命名、viewport 列表、CI 命令、設計規範，再升級成 skill。
對應的 workspace rule 可以更短：
# UI 改动验收规则
当任务修改页面、组件、样式、导航、按钮或文案时：
1. 必须跑本地构建或对应检查。
2. 必须验证 mobile 和 desktop。
3. 必须检查 console error。
4. 最终回答列出验证结果和未覆盖风险。如果這個流程重複超過三次，並且開始出現固定指令碼、viewport 列表、截圖目錄、設計標準，再建立 ui-qa Skill。
本章自檢
完成本章後，用這 3 個問題檢查自己是否真正理解：
- 一條安全紅線應該寫 Rule、Workflow 還是 Skill？
- 為什麼 workspace rules / skills 更適合商業專案？
- Skill 的
description為什麼比標題更重要？
透過標準：你能把一個反覆使用的 UI 驗收 prompt 拆成 Rule、Workflow 和 Skill 三層。
官方來源
- Google Antigravity Rules / Workflows - 官方說明 Rules、Global / Workspace 路徑、啟用方式、@mentions、Workflows 和 slash command。
- Google Antigravity Skills - 官方說明 Skills、
SKILL.md、workspace / global scope、description 和 progressive disclosure。 - Agent Skills Open Standard - 官方文件引用的 Agent Skills 開放標準入口。