---
title: "07 · Rules、Workflows、Skills 怎麼沉澱"
description: "Antigravity 長期使用的三層沉澱：Rules 管預設行為，Workflows 管按需流程，Skills 管可複用專業能力包。"
verifiedAt: "2026-05-07"
---

Antigravity 用久以後，真正拉開差距的不是 prompt 寫得多長，而是你能不能把反覆出現的要求沉澱成 Rules、Workflows 和 Skills。否則每個任務都要從頭解釋一遍，agent 也會不斷重複犯同一類錯誤。

官方文件裡，Rules 是使用者手動定義的約束，Workflows 是一組可重複執行的步驟，Skills 是帶 `SKILL.md` 的能力包。三者都能影響 agent，但職責完全不同。

> [!NOTE]
> **一句話分工**：Rules 管“每次都該遵守什麼”，Workflows 管“我主動觸發什麼流程”，Skills 管“特定任務需要載入什麼專業知識和工具”。

> [!TIP]
> **閱讀目標**：讀完本章，你應該能判斷一條經驗應該寫進 Rule、Workflow、Skill，還是繼續保留成普通 prompt。

## 1. 三者怎麼選

```mermaid
flowchart TD
    Habit["一條經驗"] --> Always{"每次都需要?"}
    Always -->|是| Rule["Rule"]
    Always -->|否| Manual{"需要我手動觸發?"}
    Manual -->|是| Workflow["Workflow"]
    Manual -->|否| Rich{"需要指令碼/模板/參考資料?"}
    Rich -->|是| Skill["Skill"]
    Rich -->|否| Prompt["普通 prompt 即可"]
```

判斷時先問三個問題：

1. 是否每次都必須遵守？是就寫 Rule。
2. 是否是一串可重複步驟？是就寫 Workflow。
3. 是否需要指令碼、模板、示例或參考資料？是就寫 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 | 某類檔案專屬約定 | 跨全專案通用約束 |

例如：

```text
Always On：禁止修改 .env、凭据目录和生产部署配置。
Glob：对 content/docs/**/*.mdx 应用教程页写作规范。
Manual：需要发布前复检时手动 @release-checklist。
Model Decision：当任务涉及 UI 改动时应用 UI 验收规则。
```

Rule 還支援 `@filename` 引用檔案。相對路徑按 Rules 檔案所在位置解釋，絕對路徑先按真實路徑解析，不存在時再回退到 workspace。團隊規則裡不要引用個人本機私有絕對路徑，否則別人無法復現。

## 4. Workflows：按需流程

Workflows 適合儲存可重複觸發的流程。例如：

```text
/ui-verify
- 启动本地服务
- 打开指定页面
- 检查 console
- desktop/mobile 截图
- 输出 walkthrough
```

適合 workflow 的特點：

1. 不是每個任務都要執行。
2. 觸發時步驟比較固定。
3. 不需要大型指令碼或大量參考檔案。
4. 使用者希望用 `/` 快速呼叫。

官方 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 寫成自由發揮。它應該包含輸入、步驟、停止點、驗收輸出。

> [!TIP]
> 走完一段任務後，可以直接讓 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/`。

最小結構：

```text
.agents/skills/
└── ui-qa/
    └── SKILL.md
```

更完整結構：

```text
.agents/skills/ui-qa/
├── SKILL.md
├── scripts/
├── examples/
└── resources/
```

`SKILL.md` 的 description 不要寫成廣告語，要寫成觸發條件（用第三人稱 + 關鍵詞，讓 agent 看一眼就知道什麼時候載入）：

```markdown
---
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 | ✅ | 可按專案覆寫 |
| 產品專屬釋出流程 |  | ✅ |

> [!IMPORTANT]
> 商業專案優先 workspace scope。只有 workspace 內的規則和 skill 才能被團隊審計、版本化和複用。

如果是個人工具，例如通用 code review skill，可以放 global；如果涉及專案命令、私有部署、內容規範、截圖路徑、釋出賬號邊界，就應該放 workspace。

## 7. 從 prompt 進化到沉澱

一個成熟演進路徑：

1. 第一次：手寫 prompt。
2. 第二次：複製 prompt，刪改。
3. 第三次：做成 workflow。
4. 出現指令碼/模板/參考檔案：升級成 skill。
5. 每次都必須遵守的部分：抽到 rule。

不要第一天就把所有東西做成 skill。先讓真實任務證明它值得沉澱。

## 8. 實戰模板

UI 驗收 workflow 可以這樣寫：

```markdown
# UI Verify

1. 启动项目本地服务。
2. 打开用户指定页面。
3. 检查 console error。
4. 分别截 desktop 与 mobile。
5. 如果有交互，录制关键路径或写 walkthrough。
6. 输出改动文件、验证结果、未覆盖风险。
```

後續如果要附帶 screenshot 命名、viewport 列表、CI 命令、設計規範，再升級成 skill。

對應的 workspace rule 可以更短：

```markdown
# UI 改动验收规则

当任务修改页面、组件、样式、导航、按钮或文案时：
1. 必须跑本地构建或对应检查。
2. 必须验证 mobile 和 desktop。
3. 必须检查 console error。
4. 最终回答列出验证结果和未覆盖风险。
```

如果這個流程重複超過三次，並且開始出現固定指令碼、viewport 列表、截圖目錄、設計標準，再建立 `ui-qa` Skill。

## 本章自檢

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

1. 一條安全紅線應該寫 Rule、Workflow 還是 Skill？
2. 為什麼 workspace rules / skills 更適合商業專案？
3. Skill 的 `description` 為什麼比標題更重要？

透過標準：你能把一個反覆使用的 UI 驗收 prompt 拆成 Rule、Workflow 和 Skill 三層。

## 官方來源

- [Google Antigravity Rules / Workflows](https://antigravity.google/docs/rules-workflows) - 官方說明 Rules、Global / Workspace 路徑、啟用方式、@mentions、Workflows 和 slash command。
- [Google Antigravity Skills](https://antigravity.google/docs/skills) - 官方說明 Skills、`SKILL.md`、workspace / global scope、description 和 progressive disclosure。
- [Agent Skills Open Standard](https://agentskills.io/home) - 官方文件引用的 Agent Skills 開放標準入口。

## 接下來去哪

<Cards>
  <Card title="MCP、許可權與 Sandbox" description="能力沉澱後，繼續收緊工具和許可權邊界。" href="/zh-Hant/docs/antigravity/understanding/08-mcp-permissions-sandbox" />
  <Card title="官方自定義查詢" description="查 Rules、Workflows、Skills 的官方路徑和結構。" href="/zh-Hant/docs/antigravity/official/04-rules-workflows-skills" />
</Cards>
