如何编写你的第一个Antigravity Skills技能:SKILL.md模板+最佳实践完整教程

原创2026-10-10 15:31:061,955 阅读

如何编写你的第一个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 或审查代码。

它的触发机制非常简单:

  1. 会话启动时,Antigravity 会加载所有已安装技能的 元数据(即 name 和 description);
  2. 你的请求与某个技能的描述匹配时,该技能被自动激活;
  3. 技能正文(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 分钟内就能上线。🚀

登录后查看全文
antigravity-skills