Gemini CLI 内置技能剖析：antigravity-support 技能的完整内容、加载机制与激活原理

本文以 Gemini CLI 仓库中自带的内置技能 antigravity-support（位于 packages/core/src/skills/builtin/antigravity-support/SKILL.md）为主体，完整解读它封装的 Antigravity CLI 安装、初始化配置与迁移指南，并深入该技能从文件解析、发现、优先级仲裁到被 activate_skill 工具激活注入的完整源码链路。读完本文，你将掌握 Agent Skill 的内容结构规范，以及 Gemini CLI 如何做到"渐进式披露"——只在会话启动时加载技能元数据、按需才把完整指令注入上下文。

一、antigravity-support 是什么

Antigravity CLI 是 Google 面向本地代码库的下一代终端智能体协作工具：它以终端用户界面（TUI）为核心，协调代码生成、推理与工作区任务。antigravity-support 是 Gemini CLI 随仓库内置的一个技能，专门用于回答用户关于安装、配置或迁移到 Antigravity CLI 的问题。

它就是一个符合 Agent Skills 开放标准的自包含目录，核心是单文件 SKILL.md，由 YAML frontmatter 元数据加 Markdown 正文两部分组成。frontmatter 决定了技能"何时被触发"：

---
name: antigravity-support
description:
  Use when the user asks questions, seeks help, or requests instructions related
  to installing, setting up, or migrating to Antigravity CLI. This skill
  provides the latest up to date details, requirements, and commands sourced
  from the official Antigravity CLI documentation.
---

其中 description 字段是技能路由的关键：Gemini 在会话启动时只会把全部技能的 name + description 注入系统提示词（由 promptProvider.ts 通过 renderAgentSkills 完成渲染），模型正是依据这段描述判断"用户问题是否匹配本技能"，再决定是否调用 activate_skill 工具。正文则遵循"渐进式披露"原则——只有被激活后才会进入对话上下文。

二、技能正文的完整知识体系

以下完整继承自 SKILL.md 的技能正文，是模型激活该技能后获得的专家级指令内容。

2.1 Antigravity CLI 核心特性

技能将 Antigravity CLI 定位为"与自主智能体协作处理本地代码库的下一代终端界面"，强调高度交互与智能体驱动，核心特性包括：

• 自主智能体协作：直接在终端内与智能体协同工作；
• 交互式 TUI：为智能体工作流设计的完整终端用户界面；
• 工作区集成：对本地工作区结构与上下文具备深层理解。

2.2 安装方式

macOS / Linux（Fast-Path 脚本），在终端执行：

curl -fsSL https://antigravity.google/cli/install.sh | bash

该脚本会下载、校验并安装最新版 Antigravity，同时自动把 agy 二进制注册进 PATH。

Windows（PowerShell），使用官方 PowerShell 安装命令：

irm https://antigravity.google/cli/install.ps1 | iex

值得一提的是，仓库中 CLI 界面展示安装信息的工具函数 antigravityUtils.ts 还覆盖了技能文档未展开的第三种 Windows 场景：当 process.platform 为 win32 且环境变量 PSModulePath 存在时返回 PowerShell 安装命令；否则（Command Prompt 环境）返回：

curl -fsSL https://antigravity.google/cli/install.cmd -o install.cmd && install.cmd && del install.cmd

macOS 与 Linux 则统一返回 install.sh 脚本命令。该函数的行为由 antigravityUtils.test.ts 逐平台断言验证。也就是说，技能文档中的两条安装路径与 UI 侧的平台探测逻辑保持同源，只是文档面向模型、代码面向界面渲染。

2.3 初始化设置与配置

安装完成后，进入任意项目或工作区目录运行：

agy

首次启动时，交互式 TUI 会引导完成三项初始化：

1. 工作区信任验证：确认对目标工作区文件夹的信任，以允许安全的本地命令执行与文件编辑；
2. 视觉主题配置：设置偏好的交互式终端外观与布局；
3. 渲染模式：根据终端能力定制 TUI 性能与绘制行为。

2.4 从其他工具（如 Gemini CLI）迁移到 Antigravity CLI

技能给出四步迁移路径：

1. 检查环境要求：确保本地满足常规依赖（node、git、shell 访问）并运行受支持的操作系统（macOS、Linux 或 Windows）；
2. 安装 Antigravity：运行上文安装脚本，使 agy 命令全局可用；
3. 验证安装：执行 agy --version 或在空目录/示例目录中启动 agy 测试；
4. 迁移工作区：直接在项目工作区根目录运行 agy，初始化助手会引导导入或配置信任策略，与迁移前使用的策略类似。

2.5 官方资源

技能将更多细节与高级配置/迁移需求指向 Antigravity CLI 官方文档（antigravity.google 的 CLI Getting Started 文档页），确保答案"以官方文档为最新来源"。

三、技能如何被解析：frontmatter 双路解析器

antigravity-support 能被发现的前提是 skillLoader.ts 能正确解析它。核心流程如下：

• 目录扫描：loadSkillsFromDir 对给定目录做 glob(['SKILL.md', '*/SKILL.md']) 扫描（忽略 node_modules 与 .git），即技能可以是目录直挂或子目录挂载两种形态。
• frontmatter 提取：用 FRONTMATTER_REGEX（/^---\r?\n([\s\S]*?)\r?\n---(?:\r?\n([\s\S]*))?/）切出 YAML 头与正文；match[2] 即成为 SkillDefinition.body——本技能中就是第二节的全部 Markdown 指令。
• 双路解析兜底：parseFrontmatter 优先用 js-yaml 解析；当 description 等值包含冒号导致 YAML 解析失败时，回退到 parseSimpleFrontmatter 的逐行正则解析器，后者还支持缩进续行的多行 description（antigravity-support 的 description 正是多行缩进格式）。
• 名称消毒：name 中的 :\/<>*?"| 等字符会被替换为 -，保证可作为文件/目录名安全使用。

解析成功的技能被封装为 SkillDefinition（含 name、description、location、body 等字段），解析失败的静默丢弃并在 debug 日志留痕。相关行为由 skillLoader.test.ts 覆盖。

四、发现与优先级：内置技能为何排第一档又"隐身"

skillManager.ts 中的 SkillManager.discoverSkills 按固定顺序组装技能库，优先级从低到高为：

1. 内置技能：discoverBuiltinSkills 从技能管理器所在目录下的 builtin/ 子目录加载（正是 antigravity-support 的存放处），并为每个技能打上 isBuiltin = true 标记；
2. 扩展技能：来自已启用扩展的 extension.skills；
3. 用户技能：~/.gemini/skills/ 及 ~/.agents/skills/ 别名目录；
4. 工作区技能：.gemini/skills/ 及 .agents/skills/ 别名（仅在文件夹受信任时加载）。

addSkillsWithPrecedence 按 name 合并：后加入者覆盖先加入者；若用户/工作区技能覆盖了内置技能，会记录 debug 警告"overriding the built-in skill"，非内置间的冲突则通过 coreEvents.emitFeedback 弹出警告。另有两条治理通道值得注意：

• 管理端开关：setAdminSettings/isAdminEnabled 允许管理员整体禁用技能；
• 按名禁用：setDisabledSkills 支持大小写不敏感地禁用指定技能（对应交互命令 /skills disable，详见 skills.md 与 using-agent-skills.md）；
• UI 隐身：getDisplayableSkills 会过滤掉 isBuiltin 技能，因此内置技能不出现在常规技能展示列表里，只能通过 /skills list all 或 gemini skills list --all 看到——这正是 antigravity-support 这类官方技能"默认可用、不占列表"的实现依据。

优先级与冲突行为由 skillManager.test.ts 验证。

五、激活链路：从提示词匹配到指令注入

当用户向 Gemini CLI 提出"怎么安装/迁移 Antigravity CLI"这类问题时，完整调用链为：

1. 提示词匹配：会话启动时技能元数据已注入系统提示词，模型判断问题匹配 antigravity-support 的 description；
2. 调用 activate_skill 工具：该工具的唯一参数是技能名 name（枚举值即为已发现技能的名称列表，见 activate-skill.ts 中 getActivateSkillDefinition(skillNames) 动态生成 schema），且只能由智能体调用，用户无法手动触发（详见 activate-skill.md）；
3. 确认环节对内置技能豁免：getConfirmationDetails 中有一处关键分支——if (skill.isBuiltin) return false;，即 antigravity-support 这类内置技能跳过用户确认对话框直接激活；非内置技能则会展示名称、描述及其资源目录结构，等待用户批准；
4. 资源放行与注入：execute 依次执行——skillManager.activateSkill(name) 记录激活状态、config.getWorkspaceContext().addDirectory(...) 把技能目录加入工作区允许路径（授予读取捆绑资源的权限）、getFolderStructure 生成技能目录结构（结果被缓存），最终返回形如：

<activated_skill name="antigravity-support">
  <instructions>
    （SKILL.md 正文：安装/配置/迁移全文指令）
  </instructions>
  <available_resources>
    （技能目录结构）
  </available_resources>
</activated_skill>

这段内容作为工具结果进入对话历史，模型随后即按技能内的安装脚本、初始化三步与迁移四步回答用户。找不到技能时，工具会返回 Skill "xxx" not found. Available skills are: ... 的错误并列出全部可用技能名，引导模型自我纠正。

六、小结与延伸阅读

antigravity-support 是理解 Gemini CLI 技能体系的一个最佳切面：它展示了标准 SKILL.md 的完整形态（frontmatter 路由 + 专家正文）、内置技能"最低优先级、无确认、UI 隐身"的特殊待遇，以及"元数据常驻、正文按需注入"的渐进式披露设计。如果你想进一步扩展，可参考：

• docs/cli/skills.md：Agent Skills 总览、发现层级与管理命令（/skills、gemini skills）；
• docs/cli/creating-skills.md：frontmatter 字段规范与自建技能指南；
• docs/tools/activate-skill.md：activate_skill 工具的参数与行为说明；
• packages/core/src/tools/activate-skill.test.ts：激活流程（含确认豁免与错误路径）的测试用例；
• packages/cli/src/ui/utils/antigravityUtils.ts 及 helpCommand.ts：CLI 帮助命令中 Antigravity 相关信息的另一消费入口。