如何编写你的第一个Antigravity Skills技能:SKILL.md模板+最佳实践完整教程
如何编写你的第一个Antigravity Skills技能:SKILL.md模板+最佳实践完整教程
想为自己的 AI 代理扩展新能力?antigravity-skills 是一个收录 300+ 专家技能的开源技能库,本文带你用 SKILL.md 模板亲手编写第一个 Antigravity Skills 技能。技能本质上就是一个目录 + 一份 SKILL.md 文件,遵循几个最佳实践后,AI 代理就能自动识别并触发你定义的工作流。🎯
什么是 Antigravity Skills:AI代理技能包的工作原理
Antigravity Skills 是给 Google Antigravity 代理的"技能包"。每个技能都教会代理完成一类特定任务,比如设计 REST API、搭建 Helm Chart 或审查代码。
它的触发机制非常简单:
- 会话启动时,Antigravity 会加载所有已安装技能的 元数据(即 name 和 description);
- 你的请求与某个技能的描述匹配时,该技能被自动激活;
- 技能正文(Instructions)指导代理按既定流程执行。
举个例子(来自 README.md):
- 你说"帮我设计一个用户服务的 REST API" → 激活
api-design-principles - 你说"审查这个 PR 的安全问题" → 激活
security-auditor
⚠️ 注意:安装的技能越多,启动时消耗的 Token 越多,误触发的概率也越高。官方建议按需精准安装,而不是全部装完。
技能目录结构:1个必需文件 + 3个可选文件夹
一个技能 = 一个目录。结构如下:
skills/
└── my-first-skill/ ← 技能目录(名字即技能ID)
├── SKILL.md ← 必需!技能的"说明书"
├── scripts/ ← 可选:辅助脚本
├── references/ ← 可选:参考文档
└── assets/ ← 可选:模板、资源文件
官方技能 helm-chart-scaffolding 就是一个完整范例,它除了 SKILL.md 外,还带有 scripts/validate-chart.sh 验证脚本、references/chart-structure.md 参考文档和 assets/Chart.yaml.template 模板文件。
目录名有两点硬性要求(由 lib/skill-schema.js 定义):
| 规则 | 说明 |
|---|---|
| 命名格式 | 只能用小写字母、数字和连字符,如 my-first-skill |
| 名称一致 | frontmatter 中的 name 必须与目录名完全相同 |
SKILL.md 模板:可直接复制的完整写法
这是官方推荐的 SKILL.md 标准模板(摘自 README.md 的 "SKILL.md Template" 一节):
---
name: <skill-name>
description: <一句话说明何时使用这个技能>
---
# <Skill Title>
## Use this skill when
- ...
## Do not use this skill when
- ...
## Instructions
1. ...
2. ...
文件由两部分组成:
① Frontmatter(YAML 元数据),只有 6 个合法字段:
| 字段 | 必填 | 限制 |
|---|---|---|
name |
✅ | ≤ 64 字符,须与目录名一致 |
description |
✅ | ≤ 1024 字符,是技能触发的关键 |
license |
❌ | ≤ 128 字符 |
compatibility |
❌ | ≤ 500 字符 |
allowed-tools |
❌ | 空格分隔的字符串 |
metadata |
❌ | 键值均为字符串的对象 |
② 正文(Markdown 指令),总行数建议 ≤ 500 行,超长会被校验工具告警。
Frontmatter 填写指南:description 决定技能能否被触发
description 是技能被自动激活的"开关",官方写作指南给出了黄金句式:
- 使用窄范围描述,例如"Use when you need to ..."(当需要……时使用)
- 明确排除场景,减少无关任务误触发
对比一下真实技能的写法,code-review-excellence 的 description(见 skills/code-review-excellence/SKILL.md):
"Master effective code review practices... Use when reviewing pull requests, establishing review standards, or mentoring developers."
"何时使用"说得很具体,而不是泛泛的"代码相关"。这就是精准触发的秘诀。🔑
三大必备正文章节:Use when、Do not use、Instructions
官方校验脚本 scripts/validate-skills.js 在严格模式下会检查三个章节,缺一不可:
| 章节标题 | 作用 | 写法建议 |
|---|---|---|
## Use this skill when |
列出适用场景 | 3~5 条具体任务 |
## Do not use |
列出排除场景 | 防止技能"抢活" |
## Instructions |
具体执行步骤 | 有序列表,动词开头 |
以 skills/api-design-principles/SKILL.md 为例,Instructions 部分只用了 4 步简洁指令(定义消费者 → 选择 API 风格 → 指定错误/版本策略 → 用示例验证),详细模式全部移入外部资源文件——这正是"正文保持精简"的最佳示范。
💡 进阶:如果技能涉及终端命令或基础设施变更,请额外增加一个 ## Safety 章节,写法参考 SECURITY.md 和 skills/antigravity-skills-manager/SKILL.md。
最佳实践清单:让技能精准触发不浪费Token
官方 Authoring Guidelines 提炼为 5 条,建议逐条对照:
- ✅ 正文精简:SKILL.md 只放核心指令,长示例移到
resources/或examples/ - ✅ 窄描述:用 "Use when..." + "Do not use" 双向界定边界
- ✅ 引用要真实:正文中用反引号引用的
resources/、references/、assets/、scripts/文件必须真实存在,否则校验直接报错 - ✅ 安全第一:涉及生产环境的技能加
## Safety章节,破坏性操作前要求确认,示例中用占位符代替密钥 - ✅ 同步索引:新增技能后重新生成目录文件(
npm run build:catalog),再依次运行npm test、STRICT=1 npm run validate:skills、npm run check:catalog三道本地检查
生成后的 CATALOG.md、catalog.json、bundles.json(精选技能包)和 aliases.json(短别名)会让你的技能可被搜索和按标签安装。
安装与验证:3步上线你的第一个技能
第 1 步:放入技能目录
技能支持两个作用域:
# 工作区级(仅当前项目生效)
cp -R skills/my-first-skill .agent/skills/
# 全局级(所有项目生效)
cp -R skills/my-first-skill ~/.gemini/antigravity/skills/
第 2 步:重启代理会话,让 Antigravity 重新扫描并加载技能元数据。
第 3 步:用触发语测试,直接说出 description 中的场景,例如"帮我……",观察技能是否被激活、指令是否按 Instructions 执行。
如果你想把技能贡献回 antigravity-skills 仓库,先克隆它:
git clone https://gitcode.com/gh_mirrors/an/antigravity-skills
然后把技能目录放入 skills/,按上一节的清单走完校验流程即可。
常见问题FAQ
Q1:技能装了但就是不触发? 90% 的原因有两个:description 写得太宽泛(和其他技能撞车),或者拷贝技能后没重启会话。先检查描述是否足够"窄"。
Q2:为什么校验报 "name must match folder name"?
name 字段和目录名必须一字不差,且都只能用小写+连字符,改一个即可。
Q3:可以一次装很多技能吗?
能不装就不装。每个技能的 name + description 都会在会话启动时计入 Token,且技能越多越容易误激活。用搜索、标签或技能包(如 core-dev)做定向安装。
总结
回顾一下你刚学会的路径:一个目录 + 一份 SKILL.md(frontmatter 写清 name 和 description,正文补齐 Use / Do not use / Instructions 三章节)→ 放入 .agent/skills/ 或全局目录 → 重启会话测试触发。照着 README.md 的模板和这份最佳实践清单,你的第一个 Antigravity Skills 技能 10 分钟内就能上线。🚀