---
title: "Skills 最佳實踐"
description: "Gemini CLI Agent Skills 最佳實踐：觸發清晰、輸入輸出固定、少依賴、避免硬編碼憑據、失敗路徑明確。"
verifiedAt: "2026-05-09"
---

好的 Skill 應該讓 Gemini CLI 更穩定，而不是讓系統更難排錯。

> [!NOTE]
> Skill 質量主要看觸發準確、流程穩定、失敗可恢復。不是 `SKILL.md` 越長越好。

## 先為發現設計

Skill 最重要的欄位是 `description`。啟用前模型只能看到名稱和描述，所以描述必須包含任務關鍵詞、觸發場景和邊界。

弱描述：

```yaml
description: Helps with security.
```

強描述：

```yaml
description: Audit a local code diff for secrets, unsafe shell commands, dependency risks, and missing tests. Use when the user asks for a security review before release.
```

描述重疊會導致誤觸發。如果兩個 Skill 都寫“review code”，模型無法穩定選擇；應該拆成 `security-review`、`performance-review`、`release-qa` 這類邊界更清楚的能力。

## 控制上下文層級

把 Skill 內容分三層：

1. `name` + `description`：常駐，越短越好。
2. `SKILL.md` 正文：啟用後載入，只放核心流程。
3. `references/`、`assets/`、`scripts/`：需要時再讀。

詳細規範、長案例、schema 不要塞進 `SKILL.md` 正文。正文越長，啟用成本越高，也越容易和專案 `GEMINI.md` 打架。

Skill 啟用後會把 `SKILL.md` 正文和目錄結構注入會話，並把 Skill 目錄加入允許讀取的路徑。所以最佳實踐不是“把所有資料都塞給模型”，而是把常用步驟放正文，把長資料放 references，把確定性處理放 scripts。

## 自由度匹配任務風險

- 高自由度：寫作、總結、探索類任務，用原則和輸出格式即可。
- 中自由度：程式碼遷移、文件標準化，用步驟和虛擬碼約束。
- 低自由度：釋出、刪除、批次改檔案、呼叫外部 API，用指令碼和少量引數固定。

脆弱任務不要只靠自然語言描述；能寫指令碼驗證的，就把指令碼放進 `scripts/`。

| 任務風險 | Skill 寫法 | 驗證重點 |
| --- | --- | --- |
| 低風險寫作 | 原則 + 輸出結構 | 風格和完整性 |
| 中風險程式碼修改 | 步驟 + 檔案邊界 | diff 和測試 |
| 高風險釋出 | 指令碼 + 人工確認 | 回復和日誌 |
| 安全審計 | 固定清單 + 掃描指令碼 | 漏檢和誤報 |
| 外部 API | MCP / Extension 分層 | 憑據和許可權 |

## 實用規則

- 觸發場景明確。
- 輸入和輸出固定。
- 每個 skill 只負責一類任務。
- 不硬編碼賬號、token、路徑。
- 失敗時說明怎麼恢復。
- 能用本地檔案說明的，不依賴模型猜。
- 危險動作保留人工確認。
- 指令碼輸出要適合模型讀取：少噪音、清楚的成功/失敗、明確下一步。
- 第三方 Skill 安裝前先讀 `SKILL.md` 和指令碼，不直接信任。

Skill 輸出也要可審計。涉及檔案修改、釋出、下載、網路請求、賬號後臺和外部 API 的 Skill，至少要說明輸入來源、寫入位置、回復方式和失敗時留下什麼產物。否則它只是一個更難排查的 prompt。

## 反模式

- 一個 skill 包辦所有事。
- 複製一堆泛泛 prompt。
- 不說明什麼時候不用。
- 把憑據寫進說明。
- 和專案 `GEMINI.md` 規則衝突。
- 在 `SKILL.md` 裡塞整本手冊，導致每次啟用都汙染上下文。
- 指令碼失敗只拋 traceback，沒有給可操作原因。

## 驗收方式

一個 Skill 至少做三項驗收：觸發是否準確，輸出是否穩定，失敗路徑是否可恢復。涉及指令碼的 Skill，還要單獨執行指令碼，確認它不依賴開發者本機私有路徑、不列印金鑰、不在失敗時留下半成品。

最好準備兩個反例 prompt：一個不該觸發 Skill，一個應該觸發但引數缺失。前者驗證邊界，後者驗證失敗路徑。如果兩種情況都能處理，Skill 才適合給團隊使用。

第三方 Skill 還要額外看指令碼許可權、網路請求、安裝後目錄訪問範圍和是否試圖讀取使用者 home 目錄。只讀完 `SKILL.md` 不夠，`scripts/` 才是高風險部分。

## 接下來去哪

<Cards>
  <Card title="啟用 Skill" description="繼續看 activate_skill、使用者確認和目錄訪問範圍。" href="/zh-Hant/docs/gemini-cli/official/04-agents-skills/43-activate-skill" />
  <Card title="建立 Skills" description="回看 SKILL.md、scripts、references、assets 的最小結構。" href="/zh-Hant/docs/gemini-cli/official/04-agents-skills/41-create-skills" />
  <Card title="Extensions" description="需要分發 Skill 時，繼續看 extension 安裝和安全審查。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/38-extensions" />
</Cards>

## 官方來源

- [Agent Skill best practices](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/skills-best-practices.md)
