Google Antigravity Agent交互UI技能开发指南

通过将原生聊天 UI 组件直接嵌入 SKILL.md 指令中，你可以将 Agent 从一个被动的文本解析器转变为一个主动的技术面试官，拥有出色的用户体验。

以下是你将从本次深入研究中获得的内容：

如何使用 Google Antigravity 交互式 UI 组件。

通过 grounding 实现用户选择的往返状态注入。

实用的设计规则，用于构建有限选择列表，而不会让开发者感到信息过载或触发视觉混乱。

📝 关于本系列：欢迎阅读《提升 Antigravity Agent 技能》系列，这是掌握 Agent 工具的 5 篇工程指南，这些工具可以减少编排负担并将 AI Agent 转变为自主协作者：ask_question、generate_image、define_subagent + invoke_subagent、send_message 和 manage_subagents。

交互式 Skill 的结构

在 Antigravity 中，Agent 能力以 Skill 的形式打包。这些是包含 SKILL.md 文件的专用目录，YAML frontmatter 用于发现，Markdown 指令用于执行。默认情况下，Agent 按顺序解释指令并执行终端命令或文件编辑。然而，当 Antigravity Agent 遇到明确调用 ask_question 工具的指令时，它会暂停执行并在聊天窗口中渲染一个原生的交互式 UI 模态框。

这个简单的工具调用桥接了 Agent 自主性与人在回路（HITL）对齐之间的鸿沟。Agent 不再猜测参数值或解析模糊的提示，而是呈现结构化的单选按钮、复选框和自由输入字段。

为了消除跨会话和子 Agent 的重复提问，我将 UI 询问与持久状态注入配对使用。我的 Agent 生命周期遵循结构化序列：

工作区状态注入（读取 user_prefs.json） 在工作流开始时，Agent 检查工作区根目录中是否存在命名空间配置文件。如果找到，它会提取保存的默认值用于 UI 展示。

交互式 UI（渲染 ask_question 模态框） Agent 使用有限选项数组和 multi-select 标志调用 ask_question，并在前面加上 "(Current Setting) " 前缀使用户立即看到当前偏好设置。

带降级处理的选项处理（清理并应用） Agent 从选中的字符串中剥离 UI 信号前缀，如果可选问题留空或跳过，则保留现有的 JSON 默认值。

状态持久化（写入 user_prefs.json） Agent 将更新的选择序列化为工作区根目录中的 user_prefs.json，为未来的子 Agent 调用建立不可动摇的事实来源。这不是一个特殊的 Antigravity 文件，而是我为项目使用而命名和创建的。你应该将这个文件命名并放置在最适合自己的位置。

内置 /grill-me 命令

在深入了解自定义 Skill 创作之前，值得注意的是 Antigravity 原生支持通过 /grill-me 斜杠命令进行交互式对齐。

当你在聊天会话中触发 /grill-me 时，Agent 会暂时暂停代码执行，进行严格的多问题面试。Agent 不会做出沉默的架构假设，而是系统性地向你询问设计权衡、边缘情况和实现边界，直到歧义消除。

虽然 /grill-me 是一个出色的内置工具，适用于临时会话规划和通用需求收集，但自定义交互式 Skills 将这个概念更进一步。通过创作调用 UI 选择模态框的自定义 Markdown Skills，工程团队可以标准化特定领域的面试工作流（如表单脚手架或云部署），并将结果答案直接持久化到工作区配置文件中，用于子 Agent grounding。

你可以在 Richard Seroter 的文章《Crafting an agent team that still includes me》中了解更多关于 /grill-me 命令的信息。

我们的交互式 UI 工作流参考演练

要查看这个架构的实际运作，请检查我如何实现示例 making-forms-demo skill。这个 skill 在生成 Web 表单之前会面试开发者，确保验证规则和标签布局符合团队标准。

图 1：当我们提示"Make a web form"时，我们的 making-forms-demo skill 被 Agent 自动发现并读入上下文。该 skill 指示 Agent 使用 ask_question 工具向用户呈现一系列问题。

Stage 1：工作区状态注入

在渲染 UI 组件之前，该 skill 指示 Agent 从 user_prefs.json 读取现有状态。

---
name: making-forms-demo
description: >
  Interviews the user for critical implementation details needed to
  generate a Web Form. Manages FORM namespace in `user_prefs.json`.
  Use when making Web Forms.
---

# Making forms
Interviews the user for critical implementation details needed to
generate a Web Form.

## Workflow Steps

1. **Confirm Intent & Hydrate State:**
   Check if `user_prefs.json` exists in the workspace root.
   If present, read the `"FORMS"` object to identify any previously
   saved preferences. Tell the user that a form has been identified
   and that a few questions must be answered (or confirmed) before
   building the form.

Stage 2：交互式 UI

如果存在之前的偏好，Agent 会用 "(Current Setting) " 作为这些字符串的前缀，并将其放在选项数组的顶部。执行时，这个 Markdown 块会生成一个支持多选复选框（is_multi_select: true）的交互式模态框。因为选项是明确枚举的，Agent 永远不会猜测验证要求。

2. **Query Validation Type:**
   Invoke the `ask_question` tool to present the user with an option
   selection UI. If previously saved values exist in 
   `user_prefs.json`, prefix those option strings with 
   `"(Current Setting) "` and list them first:
   * **Question:** "How would you like to handle field validation?
     (select all that apply)"
   * **Options:** ["Client-side validation", 
     "Server-side validation"]

   Use the selected value as `FIELD_VALIDATION_TYPE`.

Stage 3：带降级处理的选项处理

对于互斥的架构选择，该 skill 配置单选列表。通过从选项数组中省略明确的"other"字符串，Agent 自动启用 Antigravity UI 模态框中的原生默认自由输入选项。

3. **Query Validation Location:**
   Invoke the `ask_question` tool to present the user with an option
   selection UI. If a previously saved value exists in 
   `user_prefs.json`, prefix that option string with 
   `"(Current Setting) "` and list it first:
   * **Question:** "How would you like to handle validation
     messages?"
   * **Options:** ["Above the field", "Below the field", 
     "Summary Card", "Tooltip"]

   Use the selected value as `FIELD_VALIDATION_LOCATION`.

如果开发者在模态框中选择自由输入选项并输入"Inline below label"，Agent 会直接将那个自定义字符串捕获到 FIELD_VALIDATION_LOCATION 中，无需自定义语法解析。

Stage 4：状态持久化

用户提交模态框后，Agent 通过移除 "(Current Setting) " 前缀来清理输入字符串，并将最终结构写回工作区根目录：

4. **Persist User Preferences:**
   Write the user's selected form preferences to a `user_prefs.json`
   file in the workspace root directory using the `write_to_file`
   tool (or overwrite existing preferences). This guarantees that 
   future agent invocations and subagents are grounded in the user's 
   exact specifications without needing
   to re-interview them:
   ```json
   {
     "FORMS": {
       "FIELD_VALIDATION_TYPE": ["<SELECTED_VALUES>"],
       "FIELD_VALIDATION_LOCATION": "<SELECTED_VALUE>",
       "FIELD_LABEL_TYPE": "<SELECTED_VALUE>"
     }
   }

Mock Skill Instructions

Since this skill is just a mock skill for illustrating how to create interviewer UI within the chat window, don't actually create a form. Instead:

1. Write the selections to user_prefs.json in the workspace root.
2. Output the form selections to the user as confirmation using the template below:

For each field: <FIELD_NAME>: <SELECTED_VALUE>

通过将表单偏好嵌套在 "FORMS" 命名空间下，工作区配置文件保持整洁和可扩展。其他 Skills（如部署或数据库引导程序）可以在同一个 JSON 根目录下安全管理自己的状态，而不会发生冲突。

![Recalling user preferences](https://media2.dev.to/dynamic/image/width=800%2Cheight=%2Cfit=scale-down%2Cgravity=auto%2Cformat=auto/https%3A%2F%2Fdev-to-uploads.s3.us-east-2.amazonaws.com%2Fuploads%2Farticles%2Fega22ziavi64mgr96b2o.gif)

图 2：下次使用该 skill 时，它会找到之前创建的 user_prefs.json 文件，并使用该数据将适当的响应标记为"(Current Selection)"。如果用户更改了他们的选择，偏好文件也会被更新。

## 创建交互式 Skills 时要避免的 4 件事

当你的团队将自定义 Skills 从静态文本提示过渡到交互式面试官时，请遵循这四条最佳实践，以保持工作流清晰可维护：

### 1. 避免选项疲劳

交互式模态框专为快速扫描而设计。如果选择列表超过七项，用户可能会被选项淹没，转而回退到猜测。当处理大型数据集（如数百个营销活动或云区域）时，切勿将原始数组直接转储到 ask_question 块中。相反，指示 Agent 首先查询 MCP 工具，将选择过滤到与当前工作区相关的 top-5 列表，然后再渲染模态框。

### 2. 避免自由输入反模式

一个常见的错误是在 SKILL.md 的选项数组中明确添加"Other"或"Custom value"。在 Antigravity 中，ask_question 工具在呈现交互式问题时自动渲染一个默认的自由输入文本字段。明确包含"other"字符串会产生冗余且令人困惑的选项，并迫使 Agent 处理不必要的辅助文本提示步骤。

### 3. 避免配置文件中的扁平根键

将用户选择持久化到 user_prefs.json 时，始终将键值对嵌套在高级域命名空间下（如"FORMS"、"DEPLOYMENT"或"TESTING"）。如果多个 Skills 直接将扁平键写入 JSON 对象的根，随着团队 Skill 包的增长，键冲突将不可避免。命名空间保证了跨自主子 Agent 的严格边界隔离。

### 4. 避免第三人称措辞

将选项字符串格式化为用户的直接声音（例如，"Floating labels (Labels sit inside the input field)"），而不是第三人称祈使命令（例如，"Set form layout to floating"）。直接响应措辞减少了认知摩擦，使交互式模态框读起来更自然。

## 结论：停止 Prompting，开始面试

通过在聊天提示中输入大量脆弱的段落来引导自主编码 Agent 的时代已经结束。通过结合声明式 Markdown 指令、原生 ask_question UI 组件和往返 JSON 状态注入，Skill 作者可以将 AI 助手转变为严格的技术面试官。

📌 《提升 Antigravity Agent 技能》系列索引

Part 1: Building interactive UI workflows with ask_question（📍 你在这里）

Part 2: Automating Image Generation with generate_image

Part 3: Invoking Subagents with define_subagent, invoke_subagent

Part 4: Inter-Agent Communication with send_message

Part 5: Managing Active Agent Lifecycles with manage_subagents

Tool Reference: List of supported Antigravity tools

Article: How to automate modernization with Antigravity and multi-agent orchestration

Article: Crafting an agent team that still includes me

Help others find this post

Save this post to find it later.

Subscribe to my The Agentic Developer newsletter.

Share this article across social media.

Follow me on LinkedIn or X for more agentic engineering insights.