---
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="/docs/antigravity/understanding/08-mcp-permissions-sandbox" />
  <Card title="官方自定义查询" description="查 Rules、Workflows、Skills 的官方路径和结构。" href="/docs/antigravity/official/04-rules-workflows-skills" />
</Cards>
