Skills 最佳實踐
Gemini CLI Agent Skills 最佳實踐：觸發清晰、輸入輸出固定、少依賴、避免硬編碼憑據、失敗路徑明確。
好的 Skill 應該讓 Gemini CLI 更穩定，而不是讓系統更難排錯。
Skill 質量主要看觸發準確、流程穩定、失敗可恢復。不是 SKILL.md 越長越好。
先為發現設計
Skill 最重要的欄位是 description。啟用前模型只能看到名稱和描述，所以描述必須包含任務關鍵詞、觸發場景和邊界。
弱描述：
description: Helps with security.強描述：
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 內容分三層：
name+description：常駐，越短越好。SKILL.md正文：啟用後載入，只放核心流程。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/ 才是高風險部分。
接下來去哪
啟用 Skill
繼續看 activate_skill、使用者確認和目錄訪問範圍。
建立 Skills
回看 SKILL.md、scripts、references、assets 的最小結構。
Extensions
需要分發 Skill 時，繼續看 extension 安裝和安全審查。