---
title: "Skills 与渐进加载"
description: "基于官方 Skills 文档解释 Antigravity Skill 的目录结构、SKILL.md、description、workspace/global scope 和 progressive disclosure。"
verifiedAt: "2026-05-06"
---

Antigravity Skills 是扩展 agent 能力的开放标准。官方文档把 skill 定义为一个包含 `SKILL.md` 的文件夹，里面写着 agent 在特定任务中应该遵循的说明。

Skill 和 Rule、Workflow 最大的区别是：Skill 可以携带说明、最佳实践、脚本、示例和资源，并且按需加载。它适合“某类专业任务”，不适合普通一句提示词。

> [!NOTE]
> **阅读目标**：读完本章，你应该能创建一个最小 Skill，并写出能让 agent 正确触发的 description。

## 1. Skill 解决什么问题

官方文档说明，Skills 是 reusable packages of knowledge，用来扩展 agent 能做什么。每个 skill 可以包含：

- 特定任务的操作说明。
- 应遵循的最佳实践和约定。
- 可选脚本和资源。

适合做成 Skill：

| 任务 | 原因 |
| --- | --- |
| Code review | 有稳定检查清单和反馈格式 |
| Unit test generation | 有语言、框架、目录约定 |
| Release audit | 需要脚本、清单、风险边界 |
| Design screenshot review | 需要视觉标准和 viewport 规则 |
| Data migration | 需要步骤、脚本和回滚策略 |

不适合做成 Skill：

- 一次性任务。
- 很短的个人偏好。
- 单个 slash workflow 就能表达的流程。
- 没有明确触发场景的知识堆叠。

## 2. Workspace Skill 与 Global Skill

官方文档列出两个 skill scope。

| 类型 | 路径 | 适合 |
| --- | --- | --- |
| Workspace skill | `<workspace-root>/.agents/skills/<skill-folder>/` | 团队项目专属部署、测试、代码规范 |
| Global skill | `~/.gemini/antigravity/skills/<skill-folder>/` | 个人跨项目通用工具 |

官方也说明 Antigravity 默认 `.agents/skills`，并保留 `.agent/skills` 向后支持。

团队项目优先 workspace skill，因为它能随项目进入版本控制。个人跨项目工具才放 global skill。

## 3. 最小目录结构

官方给出的最小结构是：

```text
.agents/skills/
└── my-skill/
    └── SKILL.md
```

`SKILL.md` 是唯一必需文件，但可以扩展：

```text
.agents/skills/my-skill/
├── SKILL.md
├── scripts/
├── examples/
└── resources/
```

官方说明 agent 可以在执行 skill 时读取这些文件。

## 4. SKILL.md frontmatter

官方文档要求 `SKILL.md` 顶部有 YAML frontmatter。

```markdown
---
name: my-skill
description: Helps with a specific task. Use when you need to do X or Y.
---

# My Skill

Detailed instructions for the agent go here.
```

字段重点：

| Field | Required | 说明 |
| --- | --- | --- |
| `name` | No | 唯一标识；没有写时默认使用文件夹名 |
| `description` | Yes | agent 判断是否使用 skill 的关键信息 |

> [!IMPORTANT]
> description 决定触发质量。写得太泛，agent 容易误用；写得太窄，agent 可能想不到加载。

## 5. Progressive disclosure

官方文档说明 Skills 遵循 progressive disclosure：

1. Conversation 开始时，agent 看到可用 skills 的 name 和 description。
2. 如果某个 skill 看起来和任务相关，agent 才读取完整 `SKILL.md`。
3. agent 按 skill 说明执行任务。

```mermaid
flowchart TD
  Start["Conversation starts"] --> List["Agent sees skill names + descriptions"]
  List --> Match{"Description matches task"}
  Match -->|yes| Read["Read SKILL.md"]
  Match -->|no| Ignore["Do not load full skill"]
  Read --> Execute["Follow instructions / scripts / resources"]
```

这解释了为什么 Skill 不应该把 description 写成广告语。它是路由条件，不是封面文案。

## 6. 官方最佳实践怎么落地

官方 Skills 文档给出几条关键实践：

| 官方建议 | 中文落地 |
| --- | --- |
| Keep skills focused | 一个 skill 做一类任务，不做万能包 |
| Write clear descriptions | description 用第三人称，写清何时使用 |
| Use scripts as black boxes | 有脚本时先让 agent 跑 `--help`，不要先读全部源码 |
| Include decision trees | 复杂任务加决策树，帮 agent 选路径 |

示例 description：

```text
Reviews local code changes for correctness, edge cases, project conventions, tests, and release risk. Use before accepting implementation diffs or preparing a pull request.
```

这个描述比 “A powerful code review skill” 更好，因为它明确了任务、检查维度和触发场景。

<details>
<summary>深读：Skill、Rule、Workflow 怎么分工</summary>

Rule 是长期约束，Workflow 是可触发步骤，Skill 是带知识和资源的能力包。

如果一句话每次都要遵守，写 Rule。如果一串步骤经常重复，写 Workflow。如果这个任务需要专门方法、检查清单、脚本、模板、示例或参考资料，写 Skill。

不要为了显得高级把所有东西都做成 Skill。Skill 越多，description 路由越重要，维护成本也越高。
</details>

## 本章自检

完成本章后，用这 3 个问题检查自己是否真正理解：

1. `SKILL.md` 里哪个 frontmatter 字段决定 agent 是否会加载 Skill？
2. Workspace skill 和 global skill 分别适合什么场景？
3. 为什么复杂 Skill 应该包含 decision tree 或脚本 `--help` 路径？

通过标准：你能写出一个最小 Skill 目录，并用一句清晰 description 说明它什么时候应该被触发。

## 官方来源

- [Google Antigravity Skills](https://antigravity.google/docs/skills) —— 官方说明 Skills 定义、目录位置、`SKILL.md`、frontmatter、progressive disclosure 和最佳实践。
- [Agent Skills Open Standard](https://agentskills.io/home) —— 官方文档引用的 Agent Skills 开放标准入口。

## 接下来去哪

<Cards>
  <Card title="Rules 与 Workflows" description="回到长期约束和可触发流程，判断哪些内容不应该做成 Skill。" href="/docs/antigravity/official/04-rules-workflows-skills/00-rules-workflows" />
  <Card title="MCP、权限与安全" description="Skill 如果带脚本和资源，下一步必须理解工具和权限边界。" href="/docs/antigravity/official/05-mcp-permissions-security" />
</Cards>
