1. 从「重复解释规则」到 SKILL.mdAntigravity 的 Agent Skill 到底解决什么问题如果你最近在折腾 Agentic IDE大概率会遇到一个很具体的痛点每次开新会话都要把同一套项目规范、部署流程、代码审查标准重新讲一遍。讲完这一轮下一轮换个任务又得重来。Google Antigravity 官宣支持 Agent Skill 之后这个重复劳动终于有了一个可落地的载体——SKILL.md。先把概念说清楚。Google Antigravity 是一个深度集成 MCPModel Context Protocol的 Agentic IDE你可以把它理解成「VS Code MCP 工具链 技能系统 云原生上下文感知」的组合体。它和普通 AI 助手的区别在于普通助手只负责回答Antigravity 里的 Agent 能通过 MCP 挂载的工具去读日志、跑 CLI、改配置、验证修复方案。而 Agent Skill 就是给这个 Agent 发的「专业证书」——它告诉 Agent在这个项目里你应该按什么方式做事。SKILL.md是这个技能系统的核心文件。每个技能都需要一个SKILL.md文件顶部带 YAML 前置元数据下面写清楚这个技能做什么、什么时候用、有哪些脚本、遇到不同情况走哪条路径。它解决的不是「模型会不会写代码」而是「模型知不知道你团队的规矩」。这两件事完全不是一回事。适合谁来跟做这篇三类人最直接一是已经在用 Antigravity 或类似 Agentic IDE、但每次都要重复交代规则的开发者二是团队里负责搭工程规范、想让新成员快速继承流程的人三是想把 MCP 工具链和模型调用通道统一管理起来、不想每个项目各配一套 Key 的工程负责人。下面我会从 SKILL.md 模板、MCP 配置片段、本地验证步骤一路写到把模型 endpoint 和鉴权切到 TaoToken保证你能复现一次完整的 Agent 任务。2. TaoToken 前置把模型 endpoint 与鉴权统一到一条通道在动手写SKILL.md之前得先把「Agent 到底调用哪个模型、用哪个 Key」这件事定下来。Antigravity 这类 Agentic IDE 的特点是一次任务里 Agent 可能连续发起多次模型请求中间还夹着 MCP 工具调用。如果模型 endpoint 和 Key 散落在各个项目的配置文件里排障会非常痛苦——你根本不知道是哪一层鉴权挂了。我的做法是把模型调用通道统一到 TaoToken。它的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 基址是 https://taotoken.net/api 。注意这两个地址的用途不同前者用来注册、看文档、管理 Key后者是真正写进配置里的 Base URL。很多人第一次配的时候把带 UTM 的官网地址填进 Base URL结果请求直接 404这个坑后面排障章节会细说。为什么要在 Agentic IDE 场景下强调统一通道因为 Agent Skill 的执行链路是这样的你在 Antigravity 里触发一个技能 → Agent 读取SKILL.md决定策略 → 通过 MCP 调用外部工具 → 同时向模型 endpoint 发请求做推理和决策。这条链路里模型 endpoint 是唯一一个「每次任务都会命中」的环节。把它收敛到一个可控的入口你才能在一个地方看到调用量、在一个地方轮换 Key、在一个地方排查 401。具体到操作层面你需要先拿到一个可用的 API Key。进入控制台创建 Key 的路径是 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建完在 API Keys 页面可以查看和管理 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 。拿到 Key 之后先别急着往 Antigravity 里塞建议先用模型对话页面做一次最小验证确认 Key 本身是通的 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 。这一步能帮你把「Key 的问题」和「IDE 配置的问题」提前分开省掉后面大量来回试错。如果你后续要跑长期的编码任务或者多步 Agent 流程可以了解一下 Coding Plan它更适合这种持续调用的场景 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。接入细节和参数说明都在文档里 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。下面进入真正的配置环节。3. 可复制配置SKILL.md 模板 MCP 配置片段 settings 落地这一节是整篇的核心我会给出可以直接复制粘贴的三类配置SKILL.md模板、MCP 工具链配置、以及把模型 endpoint 指向 TaoToken 的 settings 片段。路径和字段名尽量贴近 Antigravity 的实际约定你按自己项目的目录结构微调即可。3.1 SKILL.md 模板一个代码审查技能先看SKILL.md的结构。文件顶部是 YAML 前置元数据必须包含name和description。description非常关键——它是 Agent 决定「要不要用这个技能」的依据所以要写具体别写「用于代码审查」这种废话要写清楚功能和使用场景。--- name: code-review description: 对当前工作区的变更做结构化代码审查覆盖命名规范、错误处理、日志埋点和测试覆盖。当用户提到 review、审查、检查改动、提交前检查时使用。 version: 1.0.0 --- # 代码审查技能 ## 何时使用 - 用户要求审查当前 diff 或某个文件 - 提交前的自检 - 新成员提交 PR 前的规范对齐 ## 执行步骤 1. 先运行 git diff --stat 确认变更范围 2. 对每个变更文件按下面的检查清单逐项过 3. 输出问题列表按严重程度排序阻断 / 建议 / 提示 ## 检查清单 - 命名变量、函数、文件命名是否符合项目约定 - 错误处理是否有未捕获的异常路径错误信息是否可定位 - 日志关键分支是否有日志日志级别是否合理 - 测试新增逻辑是否有对应测试边界条件是否覆盖 ## 脚本使用 本技能附带 scripts/check_naming.sh。不要直接读脚本源码 先运行 bash scripts/check_naming.sh --help 了解用法。 ## 决策树 - 如果变更只涉及文档 → 跳过测试检查只做命名和格式检查 - 如果变更涉及配置 → 额外检查是否有敏感信息硬编码 - 如果变更超过 500 行 → 先按模块拆分逐模块审查这里有几个最佳实践值得单独拎出来。第一保持技能专注一个技能只做好一件事别搞「包办一切」的巨型技能。第二把脚本当黑盒鼓励 Agent 先跑--help而不是通读源码这样能把上下文留给任务本身。第三复杂技能一定要写决策树让 Agent 能根据情境选路径而不是每次都走全量流程。3.2 MCP 配置片段挂载工具链Antigravity 通过 MCP 连接外部工具。下面是一个 MCP 配置片段同时挂载了文件系统工具和一个自定义的 CLI 工具。注意command和args要按你本地的实际路径改。{ mcpServers: { filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/workspace ] }, infra-cli: { command: node, args: [ /Users/yourname/.antigravity/mcp/infra-cli/index.js ], env: { INFRA_ENV: staging } } } }3.3 settings 片段把模型 endpoint 指向 TaoToken这是把模型调用通道统一到 TaoToken 的关键一步。下面是一个settings.json片段字段名按 Antigravity 的模型配置约定来写。核心是三件套Base URL、API Key、Model ID。{ agent.model: { provider: openai-compatible, baseUrl: https://taotoken.net/api, apiKey: ${env:TAOTOKEN_API_KEY}, modelId: claude-sonnet-4-20250514, maxTokens: 8192, temperature: 0.2 }, agent.skills: { workspacePath: .antigravity/skills, globalPath: ~/.antigravity/skills } }注意apiKey这里用了环境变量引用${env:TAOTOKEN_API_KEY}不要把 Key 明文写进配置文件。在终端里设置export TAOTOKEN_API_KEYsk-你的实际Key如果你用的是 Claude Code 这类工具配置方式类似Base URL 同样填https://taotoken.net/apiKey 走环境变量Model ID 按你实际要用的模型填。三件套缺一不可尤其是 Model ID填错了会直接报模型不存在。4. 验证请求跑通一次可复现的 Agent 任务配置写完不算完得验证。我建议按「先验证模型通道再验证 MCP 工具最后验证技能触发」的顺序来这样出问题能快速定位到是哪一层。4.1 验证模型通道先用一个最小请求确认模型 endpoint 是通的。如果你装了 Claude Code 或类似 CLI可以直接发一条测试请求curl -s https://taotoken.net/api/v1/messages \ -H Content-Type: application/json \ -H x-api-key: $TAOTOKEN_API_KEY \ -H anthropic-version: 2023-06-01 \ -d { model: claude-sonnet-4-20250514, max_tokens: 64, messages: [{role: user, content: 回复 OK 两个字母}] }如果返回里能看到正常的content字段和文本内容说明 Key 和 Base URL 都对。如果返回 401说明 Key 有问题如果返回 404大概率是 Base URL 写错了检查是不是误填了带 UTM 的官网地址。4.2 验证 MCP 工具挂载在 Antigravity 里打开命令面板找到 MCP 相关的状态查看入口确认filesystem和infra-cli两个 server 都显示已连接。如果某个 server 显示 failed先单独在终端里跑一遍它的command和args看是不是路径写错或者依赖没装。4.3 验证技能触发把SKILL.md放到工作区的.antigravity/skills/code-review/目录下然后在 Antigravity 里对 Agent 说「帮我审查一下当前的改动」。观察 Agent 的行为它应该先跑git diff --stat然后按检查清单逐项过最后输出分级问题列表。如果它没有触发技能八成是description写得不够具体Agent 没识别出该用这个技能。4.4 完整任务复现把上面三步串起来一次完整的 Agent 任务应该是这样的你发出指令 → Agent 读取SKILL.md确定策略 → 通过 MCP 调用git diff和文件读取工具 → 向 TaoToken 的模型 endpoint 发请求做推理 → 输出结构化审查结果。整个过程你能在 Antigravity 的日志里看到每一次模型请求和工具调用。实测下来这条链路跑通之后同一个技能在后续会话里会被自动检索和复用不用再重复交代规则。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置过程中最容易撞上的几类报错我按实际遇到的频率排一下每个都给出定位思路。401 Unauthorized。这是最高频的。先确认TAOTOKEN_API_KEY环境变量在当前 shell 里真的生效了用echo $TAOTOKEN_API_KEY看一眼。如果环境变量没问题检查配置文件里是不是写成了${env:TAOTOKEN_API_KEY}但实际字段名拼错了。还有一种情况是 Key 被轮换过但配置文件没更新去 API Keys 页面确认一下当前有效的 Key。local proxy failed。这个报错通常出现在 MCP server 启动阶段意思是本地代理进程没起来。先单独在终端跑一遍 MCP server 的启动命令看具体报什么。常见原因是npx拉包超时、Node 版本不匹配、或者args里的路径不存在。把command换成绝对路径的node或npx往往能解决。reading choices 相关报错。这类报错一般出现在模型返回格式不符合预期的时候比如 Agent 期望结构化输出但模型返回了纯文本。先检查temperature是不是设太高Agent 场景建议 0.2 以下。再检查 Model ID 是否填对不同模型对结构化输出的支持程度不一样。OAuth 相关报错。如果你用的是需要 OAuth 的工具链报错通常和 token 过期或 scope 不足有关。重新走一遍授权流程确认授予的 scope 覆盖了你要调用的工具。如果是 Claude Code 场景检查auth.json里的配置是否完整Base URL、Key、Model ID 三件套都要在。技能不触发。这个不算报错但很常见。九成是description写得太泛。把「用于代码审查」改成「当用户提到 review、审查、检查改动、提交前检查时使用」触发率会明显提升。模型返回空内容。检查maxTokens是不是设太小Agent 任务建议至少 4096。另外确认请求体里的model字段和配置里的modelId一致。6. 把通道固定下来让技能真正沉淀走到这里你已经有了一个能跑的SKILL.md、一套挂载好的 MCP 工具链、以及一条指向 TaoToken 的统一模型通道。接下来真正影响效率的是习惯层面的两件事。第一把技能当代码管理。工作区技能放进项目仓库的.antigravity/skills/目录跟着代码一起 review、一起版本化。全局技能放在~/.antigravity/skills/用来沉淀你个人的通用工作流。这样新成员 clone 下来就继承了整套规范不用你口头交代。第二把模型通道固定成环境变量别在多个项目里各写一份 Key。统一走https://taotoken.net/api这条通道轮换 Key 的时候只改一个地方。长期跑编码和 Agent 任务的话Coding Plan 会比按次调用更省心 https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 。需要查接入参数就去文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。最后留一个我踩过的坑SKILL.md的 YAML 前置元数据里description千万别用中文冒号或者特殊符号有些解析器会直接报格式错误。用标准的英文冒号加空格稳。