Gemini 中文文档Agent 技能包 (Agent Skills)
技能包（Skills）是扩展 Agent 能力的开放标准。一个技能包即为一个文件夹，其中包含一个 SKILL.md 指导文件，Agent 在处理特定任务时会遵循其中的指示。
什么是技能包？
技能包是可复用的知识包，可以扩展 Agent 的能力范围。每个技能包包含：
- 处理特定类型任务的指示
- 要遵循的最佳实践和约定
- Agent 可以使用的可选脚本和资源
当您启动对话时，Agent 会看到可用技能包的列表及其名称和描述。如果某个技能包看起来与您的任务相关，Agent 会读取完整的说明并加以遵循。
技能包存放位置 (Where skills live)
Antigravity 支持两类技能包：
| 存放路径 | 作用域 (Scope) |
|---|---|
<workspace-root>/.agents/skills/<skill-folder>/ | 工作空间特定 (Workspace-specific) |
~/.gemini/config/skills/<skill-folder>/ | 全局生效 (Global, 适用于所有工作空间) |
- 工作空间技能包非常适合特定项目的开发流，例如团队的部署流程或测试规范。
- 全局技能包适用于您的所有项目。可将个人实用程序或通用的常备工具放入其中。
[!NOTE] Antigravity 现在默认指向
.agents/skills，但仍然保留了对旧路径.agent/skills的向后兼容。
创建技能包 (Creating a skill)
要创建一个技能包：
- 在上述技能包目录之一中，为您的技能包创建一个文件夹。
- 在该文件夹中添加一个
SKILL.md文件。
.agents/skills/
└─── my-skill/
└─── SKILL.md每个技能包都需要在 SKILL.md 文件最顶部包含 YAML 属性头（Frontmatter）：
---
name: my-skill
description: 帮助处理特定任务。在需要执行 X 或 Y 时使用。
---
# 我的技能包 (My Skill)
此处填写提供给 Agent 的详细指令。
## 何时使用此技能包
- 在……时使用
- 这对……有帮助
## 如何使用
Agent 应该遵循的步骤指南、规范和模式。Frontmatter 属性字段
| 字段 | 是否必填 | 描述 |
|---|---|---|
| name | 否 | 技能包的唯一标识符（使用小写字母，空格用连字符 - 代替）。如果未提供，默认使用文件夹名称。 |
| description | 是 | 对技能包的作用以及何时使用它的清晰描述。这是 Agent 在决定是否应用该技能包时会读取的内容。 |
[!TIP] 建议使用第三人称编写您的 description，并包含一些有助于 Agent 识别技能包何时相关的关键词。例如："使用 pytest 规范生成 Python 代码的单元测试。"
技能包文件夹结构 (Skill folder structure)
虽然 SKILL.md 是唯一必填的文件，但您还可以包含其他辅助资源：
.agents/skills/my-skill/
├─── SKILL.md # 主指令文件（必填）
├─── scripts/ # 辅助脚本（可选）
├─── examples/ # 参考实现（可选）
└─── resources/ # 模板和其他资产（可选）Agent 在遵循您技能包的说明时可以读取这些文件。
Agent 如何使用技能包
技能包遵循渐进式披露（progressive disclosure）的模式：
- 探索 (Discovery)：在对话开始时，Agent 看到可用技能包的列表及其名称和描述。
- 激活 (Activation)：如果某个技能包看起来与任务相关，Agent 会读取完整的
SKILL.md内容。 - 执行 (Execution)：Agent 在处理您的任务时会遵循该技能包的指示。
您不需要显式地指示 Agent 去使用某项技能——它会根据上下文自动决策。当然，如果您希望确保使用某项技能，也可以在 Prompt 中指明该技能包的名称。
最佳实践 (Best practices)
保持技能包聚焦
每个技能包应该专注于做好一件事。不要创建“全能型”技能包，而是为不同的任务创建彼此独立的技能包。
编写清晰的描述
描述（Description）是 Agent 决定是否使用您技能包的关键。要具体说明该技能包能做什么以及它在什么情况下有用。
将脚本视作黑盒
如果您的技能包包含脚本，鼓励 Agent 先通过运行 --help 来了解如何使用，而不是读取整个脚本源码。这有助于保持 Agent 的上下文聚焦于任务本身。
包含决策树
对于复杂的技能，增加一个章节来帮助 Agent 根据实际情况选择正确的方法。
示例：代码审查技能包 (Example: A code review skill)
以下是一个帮助 Agent 进行代码审查的简单技能包示例：
---
name: code-review
description: 审查代码变更以查找 Bug、规范格式和最佳实践。在审查 PR 或检查代码质量时使用。
---
# 代码审查技能 (Code Review Skill)
在审查代码时，请遵循以下步骤：
## 审查清单
1. **正确性**：代码是否实现了预期功能？
2. **边缘情况**：错误条件是否得到妥善处理？
3. **代码风格**：是否符合项目规范？
4. **性能表现**：是否存在明显的效率低下？
## 如何提供反馈
- 具体指出需要修改的地方
- 解释原因，而不仅仅是指出问题
- 尽可能提供可替代的解决方案