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 开放标准入口。