---
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="/zh-Hant/docs/gemini-cli/official/04-agents-skills/41-create-skills" />
  <Card title="Custom commands" description="如果只是固定 slash command，不必升級成 Skill。" href="/zh-Hant/docs/gemini-cli/official/02-context-config/24-custom-commands" />
  <Card title="Extensions" description="需要分發 Skill、MCP、commands 時，繼續看 extensions。" href="/zh-Hant/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)
