---
title: "Agent Skills"
description: "Gemini CLI Agent Skills 的用途：为特定任务加载专门能力、流程、约束和上下文。"
verifiedAt: "2026-05-09"
---

Agent Skills 让 Gemini CLI 在特定任务上加载更具体的能力。它适合把重复流程、专门知识、脚本、模板和参考资料打包成可发现的能力。

> [!NOTE]
> Skill 是按需能力，不是项目常驻规则。长期项目背景放 `GEMINI.md`，重复但专门的任务流程才放 Skill。

它和 `GEMINI.md` 的区别很关键：`GEMINI.md` 是长期、常驻的项目背景；Skill 是按需激活的专门能力。这样可以避免把所有流程都塞进上下文，只有任务匹配时才加载 `SKILL.md` 和相关资源。

## 生命周期

Gemini CLI 的 Skill 流程分五步：

1. 启动时扫描已启用 Skill，只把 `name` 和 `description` 注入系统提示词。
2. 模型判断当前任务是否匹配某个 Skill。
3. 匹配后调用 `activate_skill`。
4. 用户在 UI 中确认 Skill 名称、用途和目录访问范围。
5. 通过后，`SKILL.md` 正文和目录结构进入会话，Skill 目录被加入允许读取路径。

这个机制叫 progressive disclosure。元数据常驻，正文按需加载，脚本、模板、参考资料只在需要时读取。

## 适合 Skill 的任务

- 代码审查。
- 文档生成。
- 测试修复。
- 迁移检查。
- 发布前 QA。
- 特定框架的固定流程。

## 不适合 Skill 的任务

- 一次性问题。
- 还没跑通的临时实验。
- 只有一句 prompt 就能解决的小任务。
- 含敏感凭据的流程。

| 需求 | 更适合 |
| --- | --- |
| 项目长期规则 | `GEMINI.md` |
| 重复任务入口 | Custom command |
| 专门流程 + 模板 + 脚本 | Agent Skill |
| 连接外部系统 | MCP / Extension |
| 临时一次性要求 | 当前 prompt |

## 发现层级

Gemini CLI 会按优先级发现 Skill：

1. 内置 Skill。
2. Extension 内携带的 Skill。
3. 用户级：`~/.gemini/skills/` 或 `~/.agents/skills/`。
4. 工作区级：`.gemini/skills/` 或 `.agents/skills/`。

同名时，高优先级位置覆盖低优先级位置。同一层级里，`.agents/skills/` 优先于 `.gemini/skills/`。这点适合多 Agent 工具共用同一套 Skill：想兼容 Claude/Codex/Gemini，就优先考虑 `.agents/skills/` 作为互操作入口。

## 常用管理命令

常用管理动作包括 list、install、link、uninstall、enable、disable。对应命令形如 `gemini skills list`、`gemini skills install <source>`、`gemini skills link <path>`、`gemini skills uninstall <name>`、`gemini skills enable <name>`、`gemini skills disable <name>`。

交互会话里也可以用 `/skills list`、`/skills reload`、`/skills disable <name>`、`/skills enable <name>` 管理。`enable` 和 `disable` 默认作用于 user scope；要管理工作区级 Skill，需要显式使用 workspace scope。

## 验收方式

新增或安装 Skill 后先运行 `/skills list`，确认名称、描述和 scope 正确。再用一个明确触发词发起任务，检查 Gemini CLI 是否弹出激活确认。如果没有触发，优先改 `description`，不要先往 `SKILL.md` 正文里加更多内容。

如果 Skill 被发现但不触发，通常不是正文不够长，而是描述没有写清“什么时候用”。先检查 `name`、`description`、scope、是否被 disable，再检查同名 Skill 是否被更高优先级位置覆盖。

## 接下来去哪

<Cards>
  <Card title="创建 Skills" description="继续看什么时候该新建 Skill，以及 SKILL.md 最小结构。" href="/docs/gemini-cli/official/04-agents-skills/41-create-skills" />
  <Card title="Custom commands" description="如果只是固定 slash command，不必升级成 Skill。" href="/docs/gemini-cli/official/02-context-config/24-custom-commands" />
  <Card title="Extensions" description="需要分发 Skill、MCP、commands 时，继续看 extensions。" href="/docs/gemini-cli/official/03-tools-mcp/38-extensions" />
</Cards>

## 官方来源

- [Gemini CLI Agent Skills](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills.md)
- [Using Agent Skills](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/using-agent-skills.md)
