Skills 与渐进加载
基于官方 Skills 文档解释 Antigravity Skill 的目录结构、SKILL.md、description、workspace/global scope 和 progressive disclosure。
Antigravity Skills 是扩展 agent 能力的开放标准。官方文档把 skill 定义为一个包含 SKILL.md 的文件夹，里面写着 agent 在特定任务中应该遵循的说明。
Skill 和 Rule、Workflow 最大的区别是：Skill 可以携带说明、最佳实践、脚本、示例和资源，并且按需加载。它适合“某类专业任务”，不适合普通一句提示词。
阅读目标：读完本章，你应该能创建一个最小 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. 最小目录结构
官方给出的最小结构是：
.agents/skills/
└── my-skill/
└── SKILL.mdSKILL.md 是唯一必需文件，但可以扩展：
.agents/skills/my-skill/
├── SKILL.md
├── scripts/
├── examples/
└── resources/官方说明 agent 可以在执行 skill 时读取这些文件。
4. SKILL.md frontmatter
官方文档要求 SKILL.md 顶部有 YAML frontmatter。
---
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 的关键信息 |
description 决定触发质量。写得太泛，agent 容易误用；写得太窄，agent 可能想不到加载。
5. Progressive disclosure
官方文档说明 Skills 遵循 progressive disclosure：
- Conversation 开始时，agent 看到可用 skills 的 name 和 description。
- 如果某个 skill 看起来和任务相关，agent 才读取完整
SKILL.md。 - agent 按 skill 说明执行任务。
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：
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” 更好，因为它明确了任务、检查维度和触发场景。
深读：Skill、Rule、Workflow 怎么分工
Rule 是长期约束，Workflow 是可触发步骤，Skill 是带知识和资源的能力包。
如果一句话每次都要遵守，写 Rule。如果一串步骤经常重复，写 Workflow。如果这个任务需要专门方法、检查清单、脚本、模板、示例或参考资料，写 Skill。
不要为了显得高级把所有东西都做成 Skill。Skill 越多，description 路由越重要，维护成本也越高。
本章自检
完成本章后，用这 3 个问题检查自己是否真正理解：
SKILL.md里哪个 frontmatter 字段决定 agent 是否会加载 Skill？- Workspace skill 和 global skill 分别适合什么场景？
- 为什么复杂 Skill 应该包含 decision tree 或脚本
--help路径？
通过标准：你能写出一个最小 Skill 目录，并用一句清晰 description 说明它什么时候应该被触发。
官方来源
- Google Antigravity Skills —— 官方说明 Skills 定义、目录位置、
SKILL.md、frontmatter、progressive disclosure 和最佳实践。 - Agent Skills Open Standard —— 官方文档引用的 Agent Skills 开放标准入口。