Deepseek ArtifactsDeepseek Artifacts
Google Antigravity · 自定义智能体

Antigravity 自定义智能体教程：打造你自己的专属专家

把反复出现的岗位沉淀成可保存的子智能体：在 .agents/agents 下写一个带 YAML frontmatter 的 Markdown 文件，配上有边界的工具清单，再叠上规则、工作流与技能——全部截图来自真实录屏。

开始教程常见问题

一分钟看懂

  • 自定义智能体（custom agent）就是一个 Markdown 文件：YAML frontmatter 写 name、description、model、tools，正文就是它的系统提示词——常用角色存一次，以后不用反复交代。
  • 项目级智能体放 .agents/agents/<名称>.md，随仓库共享；个人级放 ~/.gemini/config/agents/，对本机所有项目生效。
  • tools 只认 Antigravity 的真实工具名（view_file、grep_search、list_dir），写错名字智能体会直接启动失败；subagent: true 允许被委派，mainAgent: true 才会出现在输入框的选择器里。
  • 在 IDE 选择器里问它「你有哪些工具？」做冒烟测试，也可以在主对话里委派；CLI 用 /agents 查看已发现的智能体，Alt+J 打开子智能体面板。

Google Antigravity Livestream: Remote Control and Custom Agents

频道:Google Antigravity47:43

去 YouTube 观看

Antigravity Customization Features That 10X Your Coding Speed

频道:Code A Program11:02

去 YouTube 观看

Defining Custom Subagents (.md) — Antigravity Docs

官方文档:antigravity.googleDocs

去 YouTube 观看

本文截图取自 Code A Program 的纯净录屏（已署名）；自定义智能体文件的操作流程依据 Google 官方直播与 Antigravity subagents 官方文档整理——目前尚无第三方纯净录屏覆盖该流程。

事实核对另参考了 Use AI with Tech Dad 与 AI with Surya 的自定义智能体解读视频。相关商标归 Google 所有；本文为独立教程，与 Google 无隶属关系。

从空目录到可靠专家

第 1 步 · 先想清楚要不要建

  1. 1

    先判断：这个角色值得存档吗

    同一个活儿反复出现，就值得做成自定义智能体：带固定清单的代码评审员、依赖升级专员、跑测试的测试员、维护文档的文档员。判断标准三条——指令稳定、和通用助手明显不同、工具箱能提前列清楚。一次性任务别建文件，普通提示词就够了。

  2. 2

    分清自定义智能体、子智能体和技能

    子智能体（sub-agent）是「工位」：主智能体把活儿委派出去的那个会话。自定义智能体是「档案」：能坐上这个工位的存档角色，也可以被你直接对话。技能（skill）又是另一层：打包的是任何智能体都能取用的任务知识；而自定义智能体改变的是核心指令和工具权限。临时用工不用建文件——Antigravity 能在会话中用 define_subagent 工具现场生成临时子智能体。

  3. 3

    选作用域：跟仓库走还是跟机器走

    Antigravity 会在三个位置发现自定义智能体的 .md 文件。项目级放 .agents/agents/<名称>.md（或 .agents/agents/<名称>/agent.md），随仓库提交、全组共享，适合团队约定；个人级放 ~/.gemini/config/agents/<名称>.md，对本机所有项目生效；插件自带的智能体则在 plugins/<插件名>/agents/ 目录。

    Antigravity docs Rules page contrasting Global Rules stored in ~/.gemini/GEMINI.md with Workspace Rules in the .agents folder, the same global-versus-workspace split that custom agent definition files follow
    Antigravity 官方文档的 Rules 页面：全局规则放在 ~/.gemini/GEMINI.md，对所有工作区生效；工作区规则放在 .agents 文件夹——智能体文件遵循同样的划分。视频 0:30 处

第 2 步 · 写智能体文件

  1. 4

    创建智能体文件

    在项目里一次建好目录和文件——文件名或目录名就是智能体的身份，建议全小写加连字符：.agents/agents/codereviewer/agent.md。也可以直接让 Antigravity 代劳：官方直播里一句「我想做一个自定义智能体」，它就给出了完整路径 undefined/.agents/agents/codereviewer/agent.md 和一份可直接编辑的定义。

  2. 5

    填 YAML frontmatter

    frontmatter 声明这位专家的身份和边界：name 必须唯一，以后 @ 它全靠这个名字；description 决定 Antigravity 什么时候调用它，要像招聘启事一样写清楚；model: inherit 表示沿用父会话的模型档位；tools 列出它允许使用的工具。另有两个岗位开关：subagent 默认 true（可被委派），mainAgent 默认 false（改成 true 才会出现在输入框的选择器里）。

  3. 6

    写正文：系统提示词

    frontmatter 分隔线以下的所有内容就是智能体的系统指令。官方示例先立人设（「你是一名严谨细致的专业代码评审员」），再列核心职责——正确性、安全性、性能、风格——最后规定输出格式：先给 Summary 结论（通过 / 需修改），再列带行号的阻塞问题，最后是非阻塞建议。输出格式稳定，专家的报告才可信。

---
name: codereviewer
description: >-
  Code review specialist that analyzes diffs, inspects code for bugs,
  architectural issues, performance bottlenecks, and style compliance.
model: inherit
tools:
  - view_file
  - grep_search
  - list_dir
subagent: true
---

# Code Reviewer Persona & Instructions

You are an expert, meticulous Code Reviewer. Inspect proposed changes,
pull requests, and codebase files for correctness, security, performance,
and style.

## Review Output Format
- **Summary**: high-level assessment (LGTM / Changes Requested)
- **Critical findings**: blocking issues with line references and fixes
- **Suggestions & Improvements**: non-blocking refactors
一份完整的 codereviewer.agent.md：上面是 frontmatter，分隔线以下是角色设定和输出格式。工具名必须是 Antigravity 的真实名称——官方演示的初稿写成 read，直接报错。

第 3 步 · 加权限与知识

  1. 7

    用真实工具名收窄工具箱

    tools 字段是白名单，且名字必须和 Antigravity 的真实工具一致。官方直播演示时，生成的文件里写了 read，智能体直接报「Agent execution terminated due to error」，改成 view_file 才恢复。只从 view_file、grep_search、list_dir 这类真实名称里挑，并且只给角色真正需要的权限——评审员通常不需要写文件的权限。

    Antigravity workspace configuration file with a tools JSON array listing view_file, grep_search, read_file and fetch, the exact tool names a custom agent frontmatter accepts
    工作区配置文件里列出了智能体可调用的工具名——view_file、grep_search、read_file——正是自定义智能体 tools 字段要用的词汇。视频 4:44 处
  2. 8

    决定它什么时候出场

    subagent: true（默认）时，你的专家可以被委派：把任务描述给主智能体，它会把这一块工作交给专家，报告再回流到主对话。被委派的子智能体继承父会话的权限边界——命令前缀、文件读写范围、沙箱设置——需要用户批准的操作会回到主界面确认。再把 mainAgent 改成 true，专家还会出现在输入框选择器里，随时可以单独对话。

  3. 9

    打开 Customizations，新建一条规则

    给自定义智能体配上「家规」，它立刻聪明很多。在 IDE 里点智能体面板顶部的「…」下拉菜单，进入 Customizations——Rules（规则）和 Workflows（工作流）都住在这里。在 Rules 下新建规则：全局规则存在 ~/.gemini/GEMINI.md，对所有工作区生效；工作区规则放在工作区（或 git 根目录）的 .agents 文件夹里。单条规则上限 12,000 字符。

    Antigravity Customizations panel open in the agent pane with the Rules tab active and a new rule name placeholder reading e.g. code-style-guide, where workspace customizations are managed
    Antigravity 智能体面板里的 Customizations 面板：Rules 标签处于选中状态，正在输入新规则名，占位符显示 e.g. code-style-guide。视频 0:56 处
  4. 10

    选触发方式

    每条规则都要回答一个问题：什么时候生效？Always On 注入每一次对话；Manual 等你在输入框里 @ 它；Model Decision 由模型根据规则的自然语言描述自行判断；Glob 只对匹配模式的文件生效，比如 *.test.ts。选最小的够用档位——只在 diff 上触发的评审规则才不会跑偏。

    Antigravity rule Activation Mode dropdown open showing Always On, Manual, Model Decision and Glob options for controlling when a customization applies to the agent
    Antigravity 规则编辑器里的 Activation Mode 下拉框，四个选项全部展开：Always On、Manual、Model Decision、Glob。视频 1:04 处
  5. 11

    写规则内容

    规则就是纯 Markdown 约束：「注释解释为什么这么写，而不是写了什么」「函数一律写 JSDoc」「不许留 TODO」。一条规则只说一件事——智能体会逐字执行每一条命中的规则。规则塑造专家的工作方式，接下来两层再给它流程和知识。

    Antigravity rule editor with Activation Mode set to Always On and a Markdown content field describing the comments rule the coding agent will always follow
    Antigravity 编辑器里的 comments.md 规则文件，Activation Mode 设为 Always On，正等着填写每次对话都要遵守的 Markdown 指令。视频 1:02 处
  6. 12

    把固定流程做成工作流

    如果专家要反复执行一套多步流程——清理已合并分支、发版、重新生成 API 文档——就把步骤存成工作流，别每次手打。工作流是带 YAML description frontmatter 的 Markdown 文件，用斜杠命令触发：输入 /cleanup-branches，智能体按清单逐步执行。

    Antigravity docs Workflows page explaining that workflow files live in the .agent workflows folder and are invoked with a slash command, including the create-a-workflow steps
    Antigravity 官方文档的 Workflows 章节：工作流文件放在 .agent 的 workflows 目录，在对话里用斜杠命令调用。视频 5:40 处
  7. 13

    创建工作流文件

    让智能体代劳或自己动手：mkdir -p .agent/workflows，再建 cleanup-branches.md，写上一句 description frontmatter 和编号步骤清单。演示视频里的步骤从 git fetch --prune 一直到删除已合并分支——正因为每一步都写明白了，智能体在破坏性操作前会停下来请示。

    Antigravity agent conversation creating a cleanup-branches workflow with mkdir -p .agent/workflows and nano commands plus the YAML description frontmatter to paste into the markdown file
    一段 Antigravity 对话：智能体执行 mkdir -p .agent/workflows 和 nano，然后收到要保存的工作流 Markdown——description frontmatter 加十步 git 清理清单。视频 6:20 处

第 4 步 · 测试上线，分清层级

  1. 14

    亲眼看看护栏怎么工作

    演示中的工作流运行到收尾时，智能体汇报拉取结果，点名 feature/about-page 已合并、可以安全删除，然后问「要我继续删除这些吗？」——动真格之前先请示。这个习惯同样覆盖被委派的自定义智能体：需要用户授权的操作会回到主界面确认，专家不会悄悄越界。

    Antigravity agent reporting a merged feature branch as safe to delete and asking for confirmation before running git branch -d, the approval guardrail that also guards delegated sub-agents
    智能体的工作流汇报：feature/about-page 已合并、可以安全删除，并在执行 git branch -d 和 git gc 前先问「要我继续吗」。视频 7:46 处
  2. 15

    教它一门技能（skill）

    规则管行为，技能管知识。一个技能就是一个文件夹加一个 SKILL.md——工作区技能放在 .agents/skills/<技能名>/，个人技能放在 ~/.gemini/skills。frontmatter 里的 name 和 description 告诉智能体什么时候用它，正文装完整指令、脚本和参考资料。自定义智能体和技能可以组合：你的 codereviewer 可以挂一个 nextjs-reviewer 技能来补框架专项检查。

    Antigravity docs Agent Skills page with the Creating a skill steps and the .agents/skills/<skill-name>/SKILL.md folder layout that gives custom agents expert knowledge
    Antigravity 官方文档的 Agent Skills 章节：在技能目录下新建文件夹，再加一个带 YAML frontmatter 的 SKILL.md。视频 8:42 处
  3. 16

    写 SKILL.md 的 frontmatter

    description 要写成触发器：「只审 Next.js 与 TypeScript 代码的关键问题——类型、性能、安全和 App Router 模式」。请求匹配时智能体加载全文，不匹配时技能完全不碍事。这种渐进加载正是深度参考资料该放技能、而不是塞进智能体系统提示词的原因。

    Antigravity editor showing the SKILL.md frontmatter of a nextjs-reviewer skill with its name and description fields, the same YAML pattern a custom agent markdown file uses
    Antigravity 编辑器中的 nextjs-reviewer SKILL.md：frontmatter 写着技能名和描述——只审 Next.js 与 TypeScript 代码的关键问题。视频 9:16 处
  4. 17

    看技能在真实评审里生效

    演示里一句「Review the Next.js code」，智能体加载评审技能、分析页面，给出结构化评审：Project Strengths 点名类型化工具函数和字体优化，最后问「要我把这些修复应用上去吗？」才动代码。你的自定义智能体只要在提示词里要求同样的输出格式，也能继承这份克制。

    Antigravity agent reviewing a Next.js page after the reviewer skill fired, listing Project Strengths like typed utilities and next/image best practices before asking to apply fixes
    评审智能体开工：先列出项目优点——类型化工具函数、next/image、App Router 路由模式——然后询问是否应用修复。视频 10:15 处
  5. 18

    IDE 和 CLI 双端测试

    把 mainAgent 设为 true 后，专家会出现在输入框选择器里——选中它，问一句「你有哪些工具？」就能验证工具箱接对了；tools 写错会立刻报执行错误，这反而是最快的冒烟测试。CLI 里用 /agents 命令列出已发现的智能体，Alt+J 打开子智能体面板，实时跟进委派任务。

  6. 19

    提交进仓库，全组共用同一批专家

    专家需要的一切现在都在仓库里：.agents/agents/ 放智能体定义，.agent 文件夹里 rules、skills、workflows 与源码并排。提交之后，每位同事、每次 CI 都会发现同一批专家、同一套边界。~/.gemini 下的个人全局配置别提交进仓库——那是机器级的个人偏好。

    Antigravity IDE explorer showing the .agent folder with agent, rules, skills and workflows subfolders expanded next to the app source, the customization bundle that travels with the repository
    Antigravity 资源管理器里展开的 .agent 文件夹——agent、rules、skills、workflows 与源码并列，随时可以提交。视频 9:04 处
  7. 20

    分清三层：规则、工作流、技能

    这三层是智能体文件的补充而不是替代：Rules 是自动（或按模式）生效的编码规范，Workflows 是斜杠命令触发的流程，Skills 是按需自动加载的专家知识。自定义智能体则是把它们串起来的身份——一个 Markdown 文件，给重复出现的岗位一个名字、一个工具箱和一份记忆。

    Antigravity comparison table contrasting Rules, Workflows and Skills by trigger and example, from automatic coding standards to slash-command task automation and auto-discovered expert knowledge
    Rules vs Workflows vs Skills 对照表：编码规范自动生效，任务自动化走斜杠命令，专家知识按需自动发现。视频 10:20 处

自定义智能体常见问题

相关攻略

Antigravity Skills 教程Antigravity YOLO 模式教程Antigravity 接入 DeepSeek全部攻略