结论先说
- Skills(技能)是「按需翻阅的操作手册」,不同于每轮必读的 Rules(规则):Antigravity 采用 渐进式披露(Progressive Disclosure) 机制,平时只把每个技能的
name和description放进上下文,命中任务时才去读完整正文,配额开销极省。 - 标准存放位置是项目根目录下的
.agents/skills/<技能名>/SKILL.md:提交进 Git 仓库即可全团队共享;只想在自己电脑上全局通用的技能,放进~/.gemini/config/skills/。 SKILL.md顶部的description决定智能体能不能找对时机调用它:官方强烈建议用第三人称写清「这个技能做什么」以及「在用户提什么要求时必须激活」。- 长参考资料和复杂命令别全塞进主文件:把几千字的接口字典拆进同级
references/目录,把串行 Shell 命令封装进scripts/目录,用相对链接按需调用。 - 谷歌账号准备与主力编程订阅入口:使用 Antigravity 全系列客户端需登录符合开放地区与年龄条件的个人谷歌账号,缺号可查看本站 谷歌账号购买说明(含带 2FA 自动发卡的 谷歌邮箱成品号);多工具主力开发订阅总览见 AI 会员充值中心。

图:本站根据 Antigravity Skills 官方文档 整理的示意图
本文根据 Google Antigravity 官方技能文档(antigravity.google/docs/skills)整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是软件界面截图。本站(bigolab.com)不是 Google 官方网站。
适用于谁
- 想把团队内部的发版清单、数据库迁移流程或组件脚手架教给 Antigravity 反复复用的开发者;
- 发现
GEMINI.md越写越臃肿、挤占常驻上下文预算,想把长篇手册改成按需读取的人; - 原先在旧版 Gemini CLI 写过技能,想确认在 Antigravity IDE 与 2.0 桌面端里怎么组织目录的人。
一、什么时候写 Skill,什么时候写 Rule
不少团队刚开始定制工作区时,容易把所有文档一股脑全塞进 GEMINI.md。对照我们在 Antigravity Rules 规则与 24KB 预算裁剪机制 里讲过的限制,常驻规则共用 2 万 Token 预算,放太多低频 SOP 会直接挤占正常对话空间。按官方划分标准:
- 该写成 Rule 的内容:任何时候写代码都不能破的底线(例如「一律用
pnpm」「禁止改已上线的迁移文件」); - 该写成 Skill 的内容:分步骤的标准作业程序(例如「新增后台 CRUD 接口五步流程」「上线前安全自检步骤」「把国际化文案同步成多语种 JSON 的脚本调用方法」)。
此前如果你看过旧版命令行的 Gemini CLI Skills 安装与创建教程,好消息是 Antigravity 完整保留了这套以 SKILL.md 为核心的设计,并在 IDE、2.0 桌面端与 agy 命令行三端打通。如果还没配置好谷歌开发账号,可先浏览 谷歌账号购买与首登指南 或查看自动发卡的 谷歌邮箱成品号详情页(质保口径以商品页说明为准)。
二、标准目录结构与 SKILL.md 写法示范

图:本站根据 Antigravity 官方文档 整理的示意图
一个规范的自定义技能必须是 skills/ 下的一个独立文件夹(文件夹名与技能名推荐统一用小写英文加连字符),内部结构如下:
text
.agents/skills/api-contract-check/
├── SKILL.md # 必填:含顶部 YAML 元数据与主步骤说明
├── scripts/ # 可选:供智能体直接调用的辅助脚本(如校验脚本)
├── examples/ # 可选:标准输出范例或参考实现代码
├── resources/ # 可选:代码模板或静态配置文件
└── references/ # 可选:体积较大的详细规范(仅在需要时读取)
打开 SKILL.md,顶部必须包含 name 和 description 两个 YAML 字段。下面是一个可直接放进仓库复用的后端接口自检技能模板:
markdown
---
name: api-contract-check
description: >-
当用户要求新增、修改后端 REST 接口或排查前后端字段不一致时使用本技能。
负责执行 OpenAPI 契约比对、生成前端类型定义并运行接口冒烟测试。
---
# 后端接口契约核验工作流
修改或新增路由代码后,请严格按以下顺序执行并核验:
## 执行步骤
1. 阅读错误码约定(仅在新增报错分支时查阅):
[错误码字典](./references/error-codes.md)
2. 运行本地契约导出与比对脚本:
`bash .agents/skills/api-contract-check/scripts/check-openapi.sh`
3. 同步更新前端 TypeScript 类型文件:
`pnpm run gen:types`
4. 验证标准:确认终端输出 `0 breaking changes` 且 `pnpm typecheck` 零报错后再向用户汇报。
三、怎么确认技能已生效与排错要点
写完保存后,你可以通过三种办法确认并调用它:
- 在桌面端面板直观查看:打开 Antigravity 2.0 左侧边栏的「技能与定制(Skills & Customizations)」,能直接看到当前工作区已成功扫描挂载的自定义技能列表。三种客户端界面的入口对照见 Google Antigravity 下载与形态介绍。
- 自然语言自动命中或手动点名:只要你的提问匹配
description里的场景(比如「帮我新增一个退款查询接口并做契约检查」),智能体会先自动调用文件读取工具打开这份SKILL.md,再一步步往下走;你也可以在提示词里直接写出技能名让它立即加载。 - 非标准目录用
skills.json注册:如果你的多个仓库共用外部某个统一目录里的技能包,不想每个仓库都复制一遍.agents/skills/,可以在工作区通过skills.json显式声明外部路径,优先级仅次于工作区本地发现。配合按需加载技能还能显著延长高频编码周期,更多省额度办法见 Antigravity 额度限制与模型选择。
常见问题
问:写好了 SKILL.md,为什么我提问时智能体根本没去读它?
答:九成原因是顶部的 description 写得太抽象(比如只写了「后端开发助手」)。把它改成具体的触发动作描述(例如「当用户要求新建数据库迁移文件或修改 Prisma schema 时调用」),命中率会立刻提升。
问:工作区 .agents/skills/ 和全局 ~/.gemini/config/skills/ 有同名技能时听谁的?
答:按官方加载优先级,工作区项目目录优先级高于本机全局目录。同名时工作区版本会自动覆盖全局版本,方便针对个别老项目定制特殊脚本。
问:SKILL.md 里能写通用编程常识吗?
答:官方明确建议不要写模型本来就懂的基础语法常识。主文件越精炼、验证成功标准(Validation Steps)越明确,智能体执行时的走偏概率越低。
问:国内没有可用的个人谷歌账号,或者重度写代码想搭配其他编程订阅怎么办?
答:可在本站即时选购带独立 2FA 的 谷歌邮箱成品号(首登顺序与 3 天首登质保细则见 谷歌账号购买页),支持支付宝、微信支付与 AlipayHK;若日常还需要高配额终端智能体互补,也可自助兑换 Claude Code 订阅 或 ChatGPT Plus。
0 条评论
还没有评论,来抢沙发~