---
title: "Rules、Workflows 与 Skills"
description: "Antigravity 自定义体系：Rules、Workflows、Skills 的分工、global/workspace 落点、Skill 结构和渐进加载原则。"
verifiedAt: "2026-05-05"
---

Antigravity 的自定义能力分三层：Rules 是长期行为约束，Workflows 是按需触发的保存 prompt，Skills 是带元数据、说明、脚本和参考资料的能力包。三者不要混用。

> [!NOTE]
> **一句话分工**：Rules 像系统说明，Workflows 像 slash command，Skills 像可按需加载的专业工具包。

## 1. Rules

Codelab 把 Rules 描述为引导 agent 行为的 guidelines。它适合放长期稳定、每次都应该遵守的约定。

适合写进 Rules：

- 代码风格
- 测试要求
- 文件结构约定
- 命名约定
- 禁止触碰的目录
- 提交前检查

不适合写进 Rules：

- 单次任务需求
- 临时实验目标
- 过长背景材料
- 需要读取模板或脚本的流程

## 2. Workflows

Workflows 是保存 prompt，可以用 `/` 触发。它适合“不是每次都需要，但经常重复”的动作。

示例：

```text
generate-unit-tests:
- 为当前修改涉及的文件生成单元测试
- 测试文件使用同名 test_ 前缀
- 先列测试场景，等确认后再写代码
```

Workflows 的价值不是少打几个字，而是把高频动作变成一致入口。

## 3. Skills

Codelab 展示 Antigravity Skills 使用渐进披露：只有请求匹配 skill description 时，agent 才加载完整说明。典型目录：

```text
my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/
```

`SKILL.md` 需要有 frontmatter 元数据，最关键的是 `name` 和 `description`。description 决定 agent 什么时候加载这个 skill。

## 4. Global 与 workspace scope

Codelab 展示了这些落点：

| 类型 | 路径 | 适合放什么 |
| --- | --- | --- |
| Global rule | `~/.gemini/GEMINI.md` | 个人全局习惯 |
| Global workflow | `~/.gemini/antigravity/global_workflows/<name>.md` | 跨项目高频动作 |
| Workspace rules | `<workspace-root>/.agents/rules/` | 项目约定 |
| Workspace workflows | `<workspace-root>/.agents/workflows/` | 项目专属流程 |
| Global skills | `~/.gemini/antigravity/skills/<skill-folder>/` | 跨项目能力包 |
| Workspace skills | `<workspace-root>/.agents/skills/<skill-folder>/` | 项目专属能力包 |

> [!IMPORTANT]
> 团队项目优先使用 workspace scope。个人 global 配置无法进入版本控制，也无法保证团队一致。

## 5. 选择规则

```mermaid
flowchart TD
    Need["你想沉淀一条经验"] --> Always{"每次都要生效?"}
    Always -->|是| Rule["写 Rule"]
    Always -->|否| Trigger{"需要手动触发?"}
    Trigger -->|是| Workflow["写 Workflow"]
    Trigger -->|否| Package{"需要脚本/模板/参考资料?"}
    Package -->|是| Skill["写 Skill"]
    Package -->|否| Prompt["保留为普通 prompt"]

    style Rule fill:#dcfce7,stroke:#22c55e
    style Workflow fill:#dbeafe,stroke:#3b82f6
    style Skill fill:#fef3c7,stroke:#f59e0b
```

## 6. Skill 最小模板

```markdown
---
name: code-review
description: Reviews code changes for bugs, style issues, and project conventions. Use before accepting implementation diffs.
---

# Code Review

When reviewing code, check correctness, edge cases, project conventions, tests, and risk boundaries.
```

Skill 不要写成百科。它应该是“做某类任务时该怎么做”，而不是“关于某主题的一切”。

## 官方来源

- [Getting Started with Google Antigravity](https://codelabs.developers.google.com/getting-started-google-antigravity)
- [Agent Skills - Google Antigravity Documentation](https://antigravity.google/docs/skills)

## 接下来去哪

<Cards>
  <Card title="MCP、权限与安全" description="自定义能力越多，越需要明确工具和权限边界。" href="/docs/antigravity/official/05-mcp-permissions-security" />
  <Card title="Rules / Workflows / Skills 深讲" description="从原理层理解三者怎么进入长期工作流。" href="/docs/antigravity/understanding" />
</Cards>
