Agent Skills 是赋予 Antigravity agent 专业知识最强大的方式 — 但如何正确设置它们往往是大多数开发者遇到阻碍的地方。本指南将带你了解所有内容：安装社区 skill 包、修复 Windows 和 WSL2 错误、构建自定义 skills，以及在安装数百个 skills 的情况下依然保持 agent 的响应速度。
Get the latest on AI, LLMs & developer tools
New MCP servers, model updates, and guides like this one — delivered weekly.
如果你想了解 Agent Skills 背后的理论（三级加载、渐进式披露、开放标准），请参阅我们的 掌握 Agent Skills 深度解析。本文则是侧重“实操”的配套指南。
1. Skills vs Rules vs Workflows：如何选择
在安装任何内容之前，你需要了解 Antigravity 的三个配置层。将指令放在错误的地方是导致 skills 无法按预期工作的最常见原因。
GEMINI.md (Rules)
Agent 的 个性与行为。始终加载的指令，用于编码标准、风格指南和项目级规则。适用于 每一个 prompt。
适用场景：引导规则适用于每一次交互
Skills (SKILL.md)
Agent 的 专业工具箱。当 agent 检测到匹配的任务时按需加载。包含分步流程、脚本和领域知识。
适用场景：需要特定情境下的“超能力”时
AGENTS.md
该 跨工具章程。适用于 Antigravity、Claude Code、Cursor 以及其他 AI 工具的编码规范和行为规则。
适用场景：标准需要在不同工具间通用时
决策规则： 如果适用于每个 prompt，请放入 GEMINI.md。如果是针对特定任务的可复用能力，请将其设为 Skill。如果需要在多个 AI 工具中通用，请使用 AGENTS.md。有关 AGENTS.md 的深度解析，请参阅我们的 AGENTS.md 指南。
2. Skills 的运作原理：渐进式披露
Skills 使用三级加载系统，即使安装了数百个也能保持 agent 的运行速度。在开始添加 skills 之前，理解这一点至关重要 — 它解释了为什么结构良好的 skills 几乎没有性能开销，而结构糟糕的 skills 可能会拖垮你的 agent。
第一级： METADATA（始终加载）
仅限 YAML frontmatter（名称 + 描述）
每个技能约 20-50 个 tokens。零性能开销。
第 2 层： 指令（触发时加载）
当任务匹配时加载完整的 SKILL.md 正文
Agent 通过文件系统读取。200-2,000 个 tokens。
第 3 层： 资源（按需加载）
脚本、模板、schemas 保留在磁盘上
只有脚本输出（OUTPUT）进入上下文。大型资产保留在外部。
结果： 安装 100 个技能 = 约 5,000 个 tokens 开销（仅元数据）
只有被触发的技能会将完整指令添加到上下文中
这意味着你可以放心地安装数十个技能，而不必担心 Agent 的上下文窗口（context window）过载。Agent 会阅读技能描述来决定哪些内容相关，然后仅加载所需内容。欲了解更多关于 Antigravity 中上下文和 tokens 的运作方式，请参阅我们的 token 优化指南。
3. 安装技能：三种方法
方法 1：Awesome Skills 安装程序（推荐）
由社区维护的 Antigravity Awesome Skills 仓库是最大的技能集合，拥有超过 1,340 个技能，涵盖了从代码审查、数据库管理到部署自动化的方方面面。它在 GitHub 上拥有超过 29,000 颗星，是标准的入门首选。
# 默认：全局安装所有 1,340+ 个技能
npx antigravity-awesome-skills
# 特定工具安装（针对已知的技能目录）
npx antigravity-awesome-skills --antigravity
npx antigravity-awesome-skills --claude
npx antigravity-awesome-skills --cursor
npx antigravity-awesome-skills --gemini
# 安装到自定义路径
npx antigravity-awesome-skills --path ~/.my-skills/
根据社区成员的反馈，一次性安装所有 1,340+ 个技能可能会导致 Agent 首次初始化时出现 10–15 分钟的加载时间。Agent 需要读取并索引每个 SKILL.md 元数据块。请参阅下方的 性能章节 以了解如何管理此问题。
方法 2：手动安装（选择性）
对于有针对性的设置，请克隆单个技能仓库并将其 symlink 到你的技能目录中：
# 创建技能目录（如果不存在）
mkdir -p ~/.gemini/antigravity/skills
# 克隆一个技能仓库
git clone https://github.com/user/my-skill.git ~/skills-repos/my-skill
# 软链接到全局 skills 目录
ln -s ~/skills-repos/my-skill ~/.gemini/antigravity/skills/my-skill
# 或者复制到项目工作区
cp -r ~/skills-repos/my-skill ./.agent/skills/my-skill
方法 3：工作区作用域的 Skills
对于特定于项目的 skills（部署脚本、框架模板等），请将它们放置在项目的 .agent/skills/ 目录中。这些仅在该工作区内可用，非常适合提交到版本控制的团队共享 skills。
全局（所有项目）：
~/.gemini/antigravity/skills/<skill-name>/SKILL.md
工作区（仅限此项目）：
./.agent/skills/<skill-name>/SKILL.md
优先级：工作区 skills 会覆盖同名的全局 skills
4. WSL2 & Windows 设置修复
Windows 和 WSL2 用户在设置时遇到的阻碍最多。以下是针对各种常见错误的经验证修复方案：
修复：WSL2 上 Skills 无法加载
最常见的 WSL2 问题是将 skills 安装在了 Windows 文件系统中，而不是 Linux 文件系统中。运行在 WSL2 内部的 Antigravity 无法高效访问 /mnt/c/Users/... 路径 — 跨边界的文件 I/O 极其缓慢。
/mnt/c/Users/you/.gemini/antigravity/skills/
正确（WSL2 内部的原生 Linux 路径）
~/.gemini/antigravity/skills/
# 修复：将 skills 移动到原生 Linux 文件系统
mv /mnt/c/Users/you/.gemini ~/.gemini
修复：安装 Skill 后 Agent 卡在加载界面
如果在安装 skills 后，agent 在初始化期间挂起，最可靠的修复方法是彻底重启 WSL：
wsl --shutdown
# 然后重新打开 WSL 终端并重启 Antigravity
修复：WSL2 上的 OAuth / 身份验证错误
当笔记本电脑休眠时，WSL2 的时钟经常会发生偏移，导致 Google 的 OAuth 令牌因过期而被拒绝。这表现为机器从睡眠状态唤醒后突然出现身份验证失败：
sudo hwclock -s
# 或者强制进行 NTP 同步
sudo ntpdate time.google.com
修复：沙盒模式拦截 Skills (v1.21.6)
v1.21.6 更新引入了 Linux 沙盒机制，可能会阻止 skills 执行脚本。如果更新后您的 skill 脚本因权限错误而失败，请参阅我们的专用 v1.21.6 修复指南 以获取沙盒问题的解决方法。
5. Web 开发者十大核心技能
基于社区采用率和开发者反馈，以下是前端和全栈 Web 开发中最实用的技能：
| # | 技能 | 功能说明 |
|---|---|---|
| 1 | code-review | 自动化代码审查，包含安全性、性能和代码风格检查 |
| 2 | nextjs-patterns | App Router 规范、服务端组件、metadata API 最佳实践 |
| 3 | tailwind-architect | 生成符合设计系统一致性的响应式布局 |
| 4 | accessibility-audit | WCAG 2.1 合规性检查、ARIA 属性、键盘导航 |
| 5 | git-conventional | 强制执行 Conventional Commits 格式并进行范围验证 |
| 6 | api-design | REST 和 GraphQL 端点脚手架，支持生成 OpenAPI 规范 |
| 7 | test-generator | 创建具有框架感知断言的单元测试和集成测试 |
| 8 | seo-optimizer | Meta 标签、结构化数据、站点地图以及 Core Web Vitals 指导 |
| 9 | docker-compose | 为 Web 技术栈生成并验证 Docker 配置 |
| 10 | license-header | 在所有源文件中添加和管理许可证标头 |
6. 后端与系统开发者十大核心技能
| # | 技能 | 功能说明 |
|---|---|---|
| 1 | db-schema-validator | 使用 Python 脚本根据模式约束验证数据库迁移 |
| 2 | security-scanner | OWASP Top 10 检查、依赖项审计、密钥检测 |
| 3 | terraform-patterns | 基础设施即代码脚手架，包含模块最佳实践 |
| 4 | go-patterns | 惯用 Go 语言开发，包含错误处理、并发和测试模式 |
| 5 | k8s-manifests | Kubernetes 部署、服务和 Ingress 清单生成 |
| 6 | rust-patterns | 具备所有权感知的代码生成，包含生命周期和 Trait 指导 |
| 7 | ci-pipeline | GitHub Actions 和 GitLab CI/CD 流水线配置 |
| 8 | sql-optimizer | 查询分析、索引建议及执行计划审查 |
| 9 | monitoring-setup | Prometheus、Grafana 及告警配置脚手架 |
| 10 | adk-tool-scaffold | 包含模板和示例的 Google Agent Development Kit 工具生成 |
7. 创建你自己的自定义 Skill
构建一个自定义 Skill 仅需约 5 分钟。Skill 本质上只是一个包含 SKILL.md 文件的目录 — 其他所有内容都是可选的。以下是
my-skill/
SKILL.md # Required: metadata + instructions
scripts/ # Optional: Python, Bash, Node executables
references/ # Optional: templates, docs, schemas
assets/ # Optional: images, logos
examples/ # Optional: input/output demonstrations
The SKILL.md Format
Every SKILL.md has two parts: YAML frontmatter for machine discovery, and a Markdown body for human-readable instructions.
---
name: my-deployment-skill
description: Deploy the current project to staging or
production via SSH. Use when user says "deploy"
or "ship to staging".
---
# Deployment Skill
## Goal
Deploy the current project to the target environment.
## Steps
1. Read the target from user input ("staging" or "prod")
2. Run `bash scripts/deploy.sh [target]`
3. 根据脚本退出代码报告部署状态
## 约束条件
- 未经用户明确确认，绝不部署到 prod
- 部署前务必运行测试
- 如果 deploy.sh 以代码 1 退出，请报告错误
- 描述即触发器： Agent 会根据技能描述匹配用户意图。请编写具体且可操作的描述（"Deploy to staging via SSH"），而非模糊的描述（"Deployment tools"）。
- 保持脚本原子化： 每个脚本应只做一件事。让 Agent 编排多个脚本，而不是编写庞大的单体 bash 文件。
- 卸载静态内容： 大型 schema、模板和文档应存放在
references/— 而非 SKILL.md 正文中 — 以避免浪费 token。 - 包含约束条件： 告知 Agent 不该做什么。安全规则和护栏可防止 Agent 执行危险操作。
- 退出代码至关重要： 脚本成功时应返回退出代码 0，失败时返回 1。Agent 利用这些代码来决定后续步骤。
五种技能模式（复杂度递增）
- 仅指令模式： 纯 Markdown 指令，无脚本。适用于编码标准和格式化规则（例如 Conventional Commits 强制执行器）。
- 基于资产模式： 指令 + 模板文件，存放在
references/。适用于许可证头、样板生成和脚手架。 - 少样本学习 (Few-Shot Learning)： 指令 + 示例输入/输出对，存放在
examples/. Effective for type conversion (JSON to Pydantic) and format transformation. - 基于脚本模式： 指令 + 用于验证、测试或数据处理的确定性脚本。最适合需要可靠、可重复执行的任务。
- 全复合模式： 结合了模板、脚本、示例和参考资料。用于复杂的工作流，如 ADK 工具脚手架生成器。
8. 性能：保持 Agent 快速运行
最常见的性能投诉是安装许多技能后 Agent 初始化变慢。以下是实际原因及解决方法。
1,300 个技能的问题
社区成员报告称，安装完整的 Awesome Skills 库（1,340 多个技能）会导致 Agent 在首次加载时初始化耗时 10–15 分钟。这是因为 Agent 在启动期间需要读取并索引每个 SKILL.md 文件中的 YAML 元数据。
优化策略
- 选择性安装： 使用特定工具的标志（
--antigravity,--claude) 或者安装单个技能包，而不是整个库。 - 为项目技能使用工作区作用域： 位于
.agent/skills/中的技能仅为该项目加载，从而保持其他项目的运行速度。 - 定期审计： 移除不使用的技能。运行
ls ~/.gemini/antigravity/skills/ | wc -l来查看已安装的数量。 - 质量重于数量： 20–30 个精选技能的效果优于 1,300 个通用技能。
- Optimize
.antigravityignore: Ensure your ignore file excludesnode_modules,.git,dist, andbuilddirectories. This reduces indexing time for workspace skills. For a full list of what to ignore, see our agent loading optimization guide.
10-30 skills Optimal. Fast loading, precise matching.
30-100 skills Fine. Minimal overhead from metadata loading.
100-500 skills Noticeable first-load delay (30-120 seconds).
500+ skills Expect 5-15 min first init. Consider pruning.
9. Decision Guide: Skills vs GEMINI.md vs AGENTS.md
Here's the definitive decision matrix for where to put your agent instructions. Community best practice from the Google AI Developer Forum:
| Question | Answer | 用途 |
|---|---|---|
| 适用于每个提示词吗？ | 是 | GEMINI.md |
| 针对特定场景的能力？ | 是 | Skill |
| 在 Cursor/Claude 中也应该有效吗？ | 是 | AGENTS.md |
| 深度领域知识 / API 规范？ | 是 | 知识库 |
| 需要脚本或自动化？ | 是 | Skill + scripts/ |
| 团队范围的代码规范？ | 是 | AGENTS.md (提交至仓库) |
欲了解更多关于 GEMINI.md 配置的信息，请参阅我们的 包含 50 多个示例的 Antigravity 规则指南。关于跨工具标准，请参阅 AGENTS.md 指南。
随着配置规模的增长，可以创建一个 "config-layer-audit" skill，通过交叉引用 GEMINI.md、AGENTS.md 和已安装的 skills 来检测重叠、冲突和遗漏。这能防止不同层级的指令产生矛盾。