坦白说我一开始根本没有把 Antigravity 里的 skills 当回事。那时候我用它纯聊需求、写点零散代码感觉也就是个普通的人工智能对话工具。直到有一次给一个 Vue 项目做代码审查我从社区技能库拉了一个现成的 JSON 格式 skill 进去Antigravity 的行为方式立刻不一样了它会自己拆任务、自己翻项目结构、自己按清单检查组件和状态管理最后还给了带优先级的报告。那一瞬间我才意识到skills 才是让 agent 从聊天助手变成能干活同事的关键。这篇文章想把我这些天折腾 Antigravity skills 的过程完整写下来包括 skills 到底是什么、怎么把别人做好的技能装进自己的项目、怎么从零写一个能真正复用的技能以及我踩过的那几个报错——403、执行被终止、更新出错——都是怎么定位和解决的。适合两类人看一类是刚接触 skills 不知道从哪下手的另一类是已经在用但总觉得 agent 不够聪明、想自己扩展能力的。我会尽量少讲官方案例里那些空话多讲实际操作中会遇到的细节。1. 先搞清楚 Antigravity 里的 skills 到底是个什么形态很多人第一次听到 skills 会下意识把它理解成插件或者扩展程序这个类比其实容易误导。浏览器插件和 Agent 技能在加载方式、运行方式上差别很大。1.1 一个 skill 的真实构成定义文件加可选执行体Antigravity 里的 skill本质是一份结构化定义它告诉模型在什么情况下、按什么步骤、用什么工具去做某件事。最常见的形态是一个 JSON 文件里面至少包含技能的描述、触发条件、执行指令复杂的技能还可以附带一段脚本或者额外的数据文件。我习惯用一个类比来理解模型是厨师skill 是菜谱。厨师本身会做饭但如果你不给他菜谱他只能凭常识自由发挥给了菜谱之后他会严格按照步骤、配料和时间来做出品的稳定性就高很多。Antigravity 里的模型本来就具备很强的推理能力skills 干的事不是给模型装上新功能而是给模型一份当遇到这种情况就按这个流程走的行为规范。这里有个容易忽略的点skill 不是每次对话都被执行的。模型先生看到你的请求然后去比对已经加载的 skills 描述只有觉得匹配才会调用。所以 skill 的 description 写得准不准直接影响它会不会被触发。写得像产品说明书一样的东西往往在真实场景里一次都不会被唤醒。1.2 Antigravity 的加载方式是目录约定不是应用市场和手机应用商店那种集中分发模式不同Antigravity 对 skills 的态度更接近开源社区的目录约定。你不需要在某个应用市场里搜索下载而是通过三种主流方式把技能放进去在设置面板的 Skills 入口里粘贴一个 GitHub 仓库或者 JSON 文件地址直接拖入一个本地下载好的.json文件把技能文件放进项目目录下的.antigravity/skills这类约定目录中。这种设计带来的好处是技能能以纯文本形式存在可以放进 Git 仓库做版本管理可以在团队里互相分享也不需要经过任何审核。坏处也很明显——如果你不对技能来源做甄别很容易装上一些质量参差或者已经过时的东西后面我会专门写怎么规避这个问题。从实际开发体验来看Antigravity 加载 skills 的方式有点像 Cursor 或者 VS Code 里那种基于工作区配置的机制它能感知当前项目上下文并且把技能内容注入到对话的上下文窗口里。这也是为什么有些技能一旦描述太长会明显挤占对话上下文。后面讲排查执行终止问题时这个点还会再次出现。2. 三条直接把现成 skills 装进 Antigravity 的路径如果你刚开始使用 skills不建议一上来就手写。先装几个社区里口碑好的技能跑通整个流程你才能直观感受到有技能和没技能的差别。2.1 从 GitHub 仓库 URL 安装以及我踩过的两个坑在 Antigravity 的设置面板里通常能找到加号或者导入按钮选择 Add skill 后可以粘贴一个 URL。我最开始直接粘贴了某个 GitHub 仓库的主页地址结果并没有成功加载后来才发现问题出在仓库结构上。官方兼容性最好的做法是找到仓库里的一个技能清单文件比如.google/skills目录、skills/目录或者仓库根目录下*.json的技能定义文件。一些比较规范的开源技能库会直接提供一个 Copy raw file 的链接那个才是能直接被解析的格式。踩过的第一个坑是粘贴一个 GitHub 仓库主页 URLAntigravity 虽然显示已添加但实际并不能解析出可用的技能。原因是它需要的是一个明确的 JSON 资源地址而不是一个仓库索引页。第二个坑是有些技能文件并不叫skill.json而是带版本号的比如frontend-review.v2.json。如果你粘贴的 URL 指向的是那份老版本文件后续从官方源更新的时候很容易出现新旧文件并存的问题。我的建议是尽量优先使用社区中已经收录进 Antigravity 友好格式的技能库这类库往往有统一的目录结构并且会跟随 Antigravity 的格式变化做更新。粘贴 URL 之前先把这个链接放到浏览器里打开看一眼确认返回的是 JSON 内容而不是一个 HTML 页面能省掉很多来回排查的时间。2.2 从技能库网站下载 JSON 后手动导入现在很多技能站点的下载按钮拿到的就是一个单独的.json文件。这个文件拖进 Antigravity 窗口就能完成导入。整个过程看起来简单但有几个细节值得注意。首先是编码问题。有些下载站会在文件里带上 BOM 头虽然绝大多数情况下 Antigravity 能正常解析但偶尔会遇到解析器把它当成乱码字符的情况。真遇到这种问题用任意文本编辑器打开文件另存为 UTF-8 无 BOM 格式问题就解决了。其次是内容校验。下载下来的技能文件不一定都是符合最新 schema 的。比如某些早期技能用的字段名在新版本里被改过了。我自己遇到过一次json 文件能导入成功设置面板里也能看到名字但真正对话时完全不会触发。后来对比 schema 才发现它把instructions错误地写成了instruction。很多解析器为了兼容旧数据并不会在导入时报错而是直接跳过不支持字段——这正是装上了但不工作的隐蔽来源。建议下载后先用支持 JSON Schema 校验的编辑器打开或者至少用命令做一个 JSON 格式校验python -m json.tool downloaded_skill.json如果这个命令返回了格式化后的内容说明文件至少是个合法的 JSON。如果报了Expecting property name enclosed in double quotes之类的错误那就是文件本身有问题别急着导入先修复源头。2.3 项目本地 skills 目录最适合日常开发的方式如果你主要是在具体项目里用 Antigravity我最推荐的方式是建一个项目本地的 skills 目录。通常的做法是在项目根目录创建.antigravity/skills文件夹然后把技能 JSON 一个个放进去。Antigravity 会在打开项目时自动扫描这个目录。这种方式最大的好处是随项目走。每个项目需要的技能不一样前端项目可能需要页面走查、依赖审计之类的技能数据项目可能需要特征工程检查、结果验证之类的技能。把技能文件放在项目目录里团队成员 clone 代码之后技能也自然就跟过来了不需要每个人手动配置一遍。但别把这里当成万能保险箱。我见过有人把十来个技能一股脑塞进去导致每次对话时模型要在那么多技能描述里做匹配既加重了上下文负担又增加了误触发概率。我个人的经验是一个项目里常驻 3 到 5 个核心技能就够了那些偶尔用一次的技能放云端备用列表里等需要的时候再临时导入。如果你不确定 Antigravity 当前版本到底扫描哪个目录可以在对话里直接问一句请检查当前项目中有哪些 skills 可用。一般它会按照已加载配置回答你。或者去设置面板看已添加技能列表那里通常会显示每个技能来自哪个路径。2.4 装完如何验证 skill 被真正加载了这一步很关键但很多资料都不会讲。我见过太多人装完技能就直接开干结果发现 agent 表现完全没有变化然后开始怀疑整个功能是坏的。其实问题很可能是技能根本没被正确加载或者加载了但描述写得不够触发。我自己常用的验证方法有三种在对话里直接问 agent 你现在能使用哪些 skills列出名称和触发条件。它会根据当前上下文加载情况回答。如果列表里没有你刚装的技能说明导入或路径有问题。用一个非常明确、几乎不可能引发歧义的请求去触发它。比如我装了一个代码审查技能就直接说请对当前项目的 src/components 目录执行一次代码审查。如果它能按技能里的清单步骤执行说明加载没问题。观察设置面板中的技能状态。有些版本会显示每个技能的最后加载时间或者来源路径如果状态显示已启用通常就是加载成功了。验证这一步花不了两分钟但能避免后面很多混乱。尤其是从社区下载大量技能时批量导入后更应该先快速验证一遍而不是假设全都好使。3. 自己写一个可复用的 skill从需求到 JSON 的完整拆解装别人的技能始终是消耗品真正让你效率翻倍的是能把你自己项目里反复做的事情固化成技能。下面我按实际动手顺序写一下怎么从零产出一个可用的技能。3.1 最小可用三件套name、description、instructions一个最基本的技能 JSON 可以非常精简核心就是三个字段。name技能的唯一标识一般用英文小写加下划线不要带空格。比如frontend_walkthrough。description给模型看的说明决定它在什么时机调用这个技能。这一项最容易被人忽视但又最重要。instructions真正指导模型执行的内容可以是一段字符串也可以是一个步骤列表。很多人会把 description 写成这是一个前端代码审查技能这种写法其实很糟糕。模型的技能匹配机制是靠语义去判断当前用户意图和技能描述的匹配度你的描述越像一句产品介绍模型就越难在合适的时机想到它。更好的写法是当用户要求对前端项目进行页面走查、代码审查、组件质量检查时使用。执行时先梳理项目结构再检查关键文件并输出分级问题清单。看到了吗描述里包含了触发条件当……时也包含了大致的执行内容。模型不是人它不会在收到请求时认真分析这个技能好像很专业我应该用一下它只会快速匹配描述和用户请求的语义重合度。所以描述精确、具体、包含常见说法比写得高大上要有效得多。instructions 方面我的习惯是写成有序列表步骤控制在 5 到 8 步之间。不要一句请认真检查代码带过也不要写上千字的流程文档。真正好的 instructions 是可执行的边界比如检查什么、不做什么、输出什么格式。3.2 用 inputs / outputs 把参数管起来很多入门教程只讲三件套但实际使用中不加参数约束的技能很容易跑偏。你可以给技能定义输入和输出让模型在调用时知道该读取哪些参数、往哪个方向产出结果。inputs里声明这个技能需要哪些参数比如目标路径、忽略规则、自定义阈值。outputs里声明执行完成后应该输出什么结构。定义了这些之后模型在调用技能时会自动从用户请求中提取对应参数并把最终结果整理成你期望的结构。在初期你不用把参数设计得特别复杂。只放一两个最常用的比如target_path、output_format就能让技能的表现稳定很多。等到你在真实项目中跑了一段时间发现经常需要手动补充某些信息时再迭代加参数比一开始就设计一个庞大的参数体系要务实得多。还要注意一个安全问题不要在技能里写死 API Key、账号口令这类敏感信息。技能文件一旦分享出去或者进入 Git 仓库这些秘密就等于公开了。应该在技能里写从环境变量读取密钥这样的指令让模型在执行时去调用你定义的变量。3.3 实战写一个前端页面走查skill举一个我实际做过的例子。我经常需要审查 Vue 项目的代码于是写了一个frontend_walkthrough技能。核心 JSON 大概是这样的{ name: frontend_walkthrough, description: 当用户要求对前端项目做页面走查、代码审查、组件质量检查时使用。会先梳理项目结构再按固定维度检查组件、状态、样式和性能最后输出分级问题清单。, instructions: [ 1. 如果用户没有指定目录先查找 package.json 或 vite/vue 配置文件推断项目入口和目录结构。, 2. 依次读取入口页面和主要组件文件记录每个文件的核心职责。, 3. 按以下维度检查组件拆分是否合理、状态管理是否集中、样式是否隔离、是否有关键可访问性问题、有无明显性能隐患。, 4. 输出审查报告问题按 P0 阻断、P1 建议修复、P2 体验优化三个等级归类。, 5. 只输出报告不修改任何源代码。 ], inputs: { target_path: { type: string, description: 要检查的前端项目目录路径。不填时自动寻找。 }, ignore_patterns: { type: array, items: { type: string }, description: 需要忽略的文件或目录模式例如 dist、node_modules。 } }, outputs: { review_report: { type: string, description: 包含问题清单和修复建议的审查报告。 } } }这里有几个设计上的小心思值得说明。第一description 里同时出现了页面走查代码审查组件质量检查三个用户可能的说法目的就是增大触发窗口。第二第 5 条明确写只输出报告不修改源代码这个边界很重要因为 agent 默认情况下可能会顺手帮你改代码但你这次的任务只是审查。第三ignore_patterns 参数把忽略 node_modules这样的常见需求交给用户动态指定而不是写死在 instructions 里这样技能在不同项目间的复用性会更好。3.4 本地测试 skill 的几种姿势写完技能先别急着分享先在本地跑一遍。我常用的测试方法有三种。第一种直接在 Antigravity 的对话里用一个真实请求触发。比如我上面这个技能我会说请对当前项目做一次页面走查忽略 dist 目录。如果技能生效它应该自动按步骤输出分级报告。第二种固化一个最小测试请求。把你有哪些技能可用请执行前端页面走查并输出简要报告存成一个测试用的文本文件每次改完技能就丢进去跑一遍。这个方式能让回归测试变得很快避免手动重新输入。第三种先做本地格式校验。我不想把一个有语法错误的 JSON 文件直接交给 Antigravity所以会先用 Python 或者任意代码编辑器做一次解析。如果解析失败了问题通常出在多余的逗号、引号没有转义、或者字段值类型不对。另外一个我自己吃了亏才学到的做法改技能时不要直接覆盖原文件而是先复制一份在副本里改。等测试通过后再替换正式版本。因为模型对技能的解析有缓存直接覆盖有时候会遇到文件变了但行为没变的情况复制成新文件名再引入能避开这个缓存问题。4. 一次报错也不踩403、执行终止和更新失败怎么定位Antigravity 用多了迟早会遇到几个报错。我在社区里看到最常见的就是 403、agent execution terminated due to error.和更新失败。下面按我的实际排查思路展开。4.1 403 出现的真正原因和检查顺序很多看到 403 就会往网络拦截、访问限制那方面想但在 Antigravity 的语境下403 最常见的几个原因其实是这些会话过期或者登录状态失效重新登录后往往就恢复。当前账号没有使用某个模型或功能的权限尤其是企业账号在管理员没有开通对应能力时。你的某个技能或者代码里尝试访问的资源需要额外的身份认证但当前会话没有携带有效凭证。请求中携带的内容触发了服务端的访问控制策略这种最常见于反复测试同一段异常输入时。排查顺序我觉得应该是先确认登录状态再看当前项目选用的模型是否支持技能调用然后把报错信息和上下文贴给官方支持渠道确认。不要一上来就怀疑是不是技能文件写错了因为 403 是典型的权限类错误和技能内容本身通常没有直接关系。这里也要提醒一句不要为了让 403 消失而去折腾什么非官方访问方式。正常路径下重新登录、检查账号权限、或者联系管理员开通对应模型访问权限基本都能解决。如果这些都不行那就说明当前资源对你不可用换个思路比绕道更稳妥。4.2 agent execution terminated due to error.的完整排查链路这个报错信息其实很模糊它只告诉你代理在执行过程中被终止了但不告诉你为什么。我总结了一条相对完整的排查链路遇到这类错误时可以按顺序走。第一步先看日志和错误面板。Antigravity 一般会在报错旁边显示更详细的上下文比如是调用外部工具时出错还是模型输出解析失败又或者是模型输出内容超过了长度限制。只看这行模糊的提示就放弃的话你很难定位问题。第二步缩小范围。如果你同时启用了多个技能先全部禁用只保留出问题时刻正在执行的那个技能再重新触发一次请求。很多误导性错误其实来自技能之间的冲突比如两个技能都往输出里追加了内容导致最终结果格式崩坏。第三步检查技能的 instructions。最常见的一个坑是指令里写了类似请逐步展示所有思考过程这样的话。模型为了完整展示思考链输出非常长一旦超过输出上限整个执行过程就被切断了。我当时遇到这个问题时改掉指令里面的逐步思考表述换成直接输出结论和关键依据再跑就正常了。第四步检查技能是否依赖外部脚本。如果你的技能附带了一个 Python 脚本脚本里某个依赖没装好agent 在执行时调用不到也会导致执行终止。解决方法是在技能说明里写清楚环境要求让模型执行前先做环境检查。第五步尝试切换一个上下文窗口更大的模型。有些技能本身指令很大再加上项目源码内容小上下文窗口很容易在中间步骤被截断。这个原因最隐蔽因为它不是能不能答的问题而是答不完的问题。4.3 更新出错大概率是缓存和旧目录在作祟网上很多人说 Antigravity 更新出错我自己也遇到过。但绝大多数案例都不是官方服务出了问题而是本地缓存和旧文件没清理干净。比如你从 GitHub 添加了一个技能后来仓库作者更新了版本你在 Antigravity 里点击刷新结果还是旧的。这种情况通常是因为本地已经缓存了旧版技能文件。处理办法也很简单先把旧技能从已添加列表里移除再重新粘贴远程 URL 添加一次。如果还不行就去项目目录里找有没有残留的旧技能文件手动删掉后再加。还有一种情况是更新出错四个字出现在 Antigravity 自身更新过程里。这通常是临时网络波动检查网络连接后重启应用再试一次就行。如果反复失败那就看看本机是否还有旧版本残留卸载后重新安装官方版本一般能解决。我个人的习惯是技能更新不追求第一时间同步。除非新版本修复了一个我正在踩的 bug否则我不会频繁刷新。因为每次更新后都需要重新验证一遍触发效果这个时间成本比想象中高。4.4 常见错误对照表现象、原因、优先动作错误现象可能原因优先排查动作返回 403 错误会话过期、账号无模型权限、技能引用了受限资源重新登录确认账号权限暂时禁用相关技能再试提示agent execution terminated due to error.输出超长、指令互相冲突、外部脚本依赖缺失按上文五步链路逐项排查优先看错误详情和指令长度技能更新后仍是旧行为本地缓存了旧文件移除技能后重新导入清理项目目录下的旧技能文件技能已添加但对话从不触发描述写得像产品介绍、字段名不兼容重写 description 加入触发条件用 JSON 校验工具检查字段导入提示格式错误文件不是合法 JSON 或带 BOM用python -m json.tool校验另存为 UTF-8 无 BOM这张表是我每次帮朋友排查问题时都会先给出来的。大多数问题不是秘密而是大家跳过了最基础的排查顺序一上来就找复杂原因。5. 让 skills 变成超级能力的四个使用习惯社区里有人喜欢把所有的高性能技能统称为 superpower skills听起来很玄其实没那么神秘。真正让技能产生超级能力的是使用方式和组合方式。我总结了自己一直在用的四个习惯。5.1 description 要写成触发钩子不是产品介绍这可能是整篇文章里最值得记住的一句话。技能描述写得好不好直接决定模型会不会在正确的时候想起它。我会把描述拆成两个部分触发条件 执行范围。触发条件是当用户要求 X 时使用此技能执行范围是它会做 Y 并输出 Z。这两部分越贴近用户真实会说的话触发准确率就越高。相反如果你写这是一个高效的前端代码审查工具模型会选择性地忽略它因为这句话不像一个触发信号更像一句宣传标语。5.2 一个 skill 只干一件事组合优于大而全我见过很多人想把所有需求塞进一个技能里比如一个万能开发助手技能里面又是代码生成、又是代码审查、又是部署检查。结果就是每次模型都在为一堆复杂指令进行权衡执行质量反而不稳定。我的做法是把一个较大的工作流拆成多个小技能然后用一个主技能串联它们。举例来说前端审查流程可以拆成依赖安全检查页面走查性能基础评估三个技能再写一个frontend_audit_runner技能在 instructions 里告诉模型依次调用这三个技能并汇总结果。这样每个小技能都简洁、可测试、可独立复用主技能负责编排出问题时也容易定位是哪一环失败。5.3 把 skills 纳入版本管理错了能回滚技能文件本质上是文本是文本就应该放进 Git。我自己会在项目的.antigravity/skills目录下做版本管理每次修改技能后提交一次变更说明。这样做的价值在团队协作时特别明显如果有人改动了一个技能导致 agent 行为异常你可以通过 git diff 看到具体改了什么然后快速回滚。如果技能是全局使用的不在某个项目里我也会把这些 JSON 文件统一放在一个私有仓库里管理再从仓库地址加载到 Antigravity。这比散落在本地文件夹里要可靠得多。至少删了还能拉回来。5.4 社区技能库的三查原则最后说说安全意识。现在网上有大量技能库下载前我会坚持做三个检查。查来源看这个技能库有没有明确的作者和更新记录star 数量和 issue 活跃度只能作为参考关键看它是否还在持续维护。查权限技能文件里有没有要求填写 API Key有没有把密钥写死在内容里有没有要求 agent 去访问外部不明 endpoint如果技能会向一个你不认识的地址发送请求我建议直接放弃。查依赖它的指令依赖哪个模型能力如果依赖一个只有付费版本才能使用的模型而你当前用的是基础版装上去大概率只会增加干扰。这三个检查花不了几分钟但能避免把不可信的执行逻辑引入到你的项目上下文中。我在实际使用中最深的一个体会是skills 改变的不只是 Antigravity 的输出质量更是我使用它的方式。以前我是给 agent 下一个完整命令然后祈祷它理解现在我是把复杂的判断流程整理成技能让 agent 每次都能用同一种高质量的标准去执行。这个转变的价值比多写几个技能本身要大得多。如果你也想让 Antigravity 从有时候好用变成稳定好用我建议从小处开始先把一个你最常做的事固化成技能再慢慢扩充你的技能库。