Agent Skills
Gemini CLI Agent Skills 的用途：為特定任務載入專門能力、流程、約束和上下文。
Agent Skills 讓 Gemini CLI 在特定任務上載入更具體的能力。它適合把重複流程、專門知識、指令碼、模板和參考資料打包成可發現的能力。
Skill 是按需能力，不是專案常駐規則。長期專案背景放 GEMINI.md，重複但專門的任務流程才放 Skill。
它和 GEMINI.md 的區別很關鍵：GEMINI.md 是長期、常駐的專案背景；Skill 是按需啟用的專門能力。這樣可以避免把所有流程都塞進上下文，只有任務匹配時才載入 SKILL.md 和相關資源。
生命週期
Gemini CLI 的 Skill 流程分五步：
- 啟動時掃描已啟用 Skill，只把
name和description注入系統提示詞。 - 模型判斷當前任務是否匹配某個 Skill。
- 匹配後呼叫
activate_skill。 - 使用者在 UI 中確認 Skill 名稱、用途和目錄訪問範圍。
- 透過後，
SKILL.md正文和目錄結構進入會話，Skill 目錄被加入允許讀取路徑。
這個機制叫 progressive disclosure。後設資料常駐，正文按需載入，指令碼、模板、參考資料只在需要時讀取。
適合 Skill 的任務
- 程式碼審查。
- 文件生成。
- 測試修復。
- 遷移檢查。
- 釋出前 QA。
- 特定框架的固定流程。
不適合 Skill 的任務
- 一次性問題。
- 還沒跑通的臨時實驗。
- 只有一句 prompt 就能解決的小任務。
- 含敏感憑據的流程。
| 需求 | 更適合 |
|---|---|
| 專案長期規則 | GEMINI.md |
| 重複任務入口 | Custom command |
| 專門流程 + 模板 + 指令碼 | Agent Skill |
| 連線外部系統 | MCP / Extension |
| 臨時一次性要求 | 當前 prompt |
發現層級
Gemini CLI 會按優先順序發現 Skill：
- 內建 Skill。
- Extension 內攜帶的 Skill。
- 使用者級：
~/.gemini/skills/或~/.agents/skills/。 - 工作區級：
.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 是否被更高優先順序位置覆蓋。
接下來去哪
建立 Skills
繼續看什麼時候該新建 Skill，以及 SKILL.md 最小結構。
Custom commands
如果只是固定 slash command，不必升級成 Skill。
Extensions
需要分發 Skill、MCP、commands 時，繼續看 extensions。