建立 Skills
Gemini CLI 建立 Agent Skill 的判斷標準：什麼時候應該沉澱、結構如何保持小、如何避免把一次性任務過度工程化。
📖 本篇術語速查表
| 英文 / 縮寫 | 中文 | 一句話解釋 |
|---|---|---|
| 建立 Skill | create | 寫一個可用的 Skill 定義。 |
| 結構 | structure | 觸發 / 步驟 / 驗證 / 邊界。 |
| 描述 | description | 決定觸發準確性的關鍵。 |
不想讀完？把下面這段提示詞丟給 AI 幫你跑完——幫你把一個重複流程做成結構清晰、能準確觸發的 Skill。
你是 Gemini CLI Skill 建立顧問。
【角色】
Gemini CLI Skill 建立顧問，按最小夠用、安全優先的原則給可落地方案，每條結論都落到能照做的步驟或示例，不停留在空泛建議。
【輸入】
- 想沉澱成 Skill 的流程：___
- 觸發時機和輸入：___
- 期望輸出：___
- 儲存位置 / 分發需求：___
- 經驗水平：___
【工作流程】
1. 提煉流程結構
2. 寫 Skill 骨架（觸發 / 輸入 / 步驟 / 輸出 / 驗證 / 邊界）
3. 寫準確的觸發描述
4. 給儲存和分發
5. 給驗證
【輸出規範】
▌一、Skill 骨架
▌二、準確的觸發描述
▌三、儲存與分發
▌四、驗證
【硬約束】
- 描述準確反映用途
- 邊界（不該做什麼）寫清
- 指令碼類可審查，不藏黑盒
- 不要替我臆測情況或編造不存在的能力，資訊不全先問清
- 不確定的設定或介面一律以官方文件為準，禁止照搬過時寫法建立 Skill 的前提不是“這個功能很酷”，而是“這個任務會重複出現，而且每次都需要同一套步驟和約束”。
先跑通流程，再沉澱 Skill。沒驗證過的流程寫進 Skill，只會把一次性混亂變成長期混亂。
建立前檢查
| 問題 | 如果答案是 no |
|---|---|
| 這個任務會重複嗎 | 不要建 skill |
| 流程已經跑透過嗎 | 先手工跑一次 |
| 輸入輸出能固定嗎 | 先整理契約 |
| 風險邊界清楚嗎 | 先補安全說明 |
| 比 custom command 更復雜嗎 | 簡單任務用 custom command |
推薦目錄
SKILL.md 是唯一必需檔案，但真實 Skill 通常需要把確定性部分拆出來：
my-skill/
├── SKILL.md
├── scripts/
├── references/
└── assets/scripts/放可重複執行的檢查、轉換、採集指令碼。references/放長規範、schema、API 說明、示例報告。assets/放模板、樣例檔案、非執行資源。
Skill 啟用後，模型會獲得整個目錄的讀取許可權。目錄裡不要放憑據、客戶原始資料或本機專屬路徑。
官方發現層級包括 built-in、extension、user 和 workspace。個人長期能力放 ~/.gemini/skills/ 或 ~/.agents/skills/；專案共享能力放 .gemini/skills/ 或 .agents/skills/。團隊教學裡要明確 scope，否則讀者可能把個人 Skill 誤提交到專案儲存庫。
SKILL.md 最小結構
SKILL.md 使用 YAML frontmatter。name 要和目錄名一致，description 是觸發器，必須寫“什麼時候用”，而不是泛泛描述能力。
---
name: code-reviewer
description: Review local code changes for correctness, security, and style. Use when the user asks to review a diff or PR.
---
# Code Reviewer
1. Inspect the changed files.
2. Run the bundled deterministic checks when available.
3. Report bugs first, then risks, then missing tests.一個好的 description 應該包含觸發詞、任務邊界和不該觸發的邊界。模型在啟用前只看得到這段後設資料。
官方也提供校驗和打包指令碼思路：先 validate，再 package。實際團隊不一定直接使用官方指令碼，但必須保留同等驗收：frontmatter 可解析、name 與目錄一致、description 能觸發正確任務、目錄裡沒有憑據和本機路徑。
Skill 應該小
一個 skill 只解決一類任務。不要把“寫文章、發站點、配圖、SEO、GitHub 釋出”塞進一個 skill。複雜流程交給工作流編排。
Skill 和 command 的取捨
| 情況 | 建議 |
|---|---|
| 只需要一條固定 prompt | Custom command |
| 需要指令碼、模板、參考資料 | Skill |
| 需要外部 API 或服務 | MCP / Extension |
| 需要多個階段和人工驗收 | 工作流 + Skill |
| 還沒複用超過 3 次 | 先不要建 Skill |
Skill 的價值在於按需載入完整能力包。越是低風險、短流程、單輸入輸出的任務，越應該先用 command 或普通文件，不要過度工程化。
建立方式
最快方式是讓 Gemini CLI 使用內建 skill-creator 生成骨架。手工建立時，把 Skill 放到 .gemini/skills/<name>/ 或 .agents/skills/<name>/。如果是團隊共享，放工作區目錄並進入版本管理；如果只是個人能力，放 ~/.gemini/skills/ 或 ~/.agents/skills/。
本地開發獨立 Skill 儲存庫時，用 gemini skills link . 連結測試。要分發給別人，可以作為 extension、單獨 Git 儲存庫，或工作區內共享目錄。
安裝第三方 Skill 時不要直接跳過 consent。終端安裝命令可能提供 --consent 這類跳過確認的選項，它適合自動化受控環境，不適合普通教學預設使用。
驗收方式
建立後重啟或執行 /skills reload，再執行 /skills list 檢查是否被發現。觸發測試要覆蓋兩類輸入：一個應該啟用 Skill，一個不應該啟用 Skill。能區分這兩類，說明 description 才算寫對。
接下來去哪
Skills 最佳實踐
繼續看 description、上下文層級、指令碼和失敗路徑怎麼設計。
啟用 Skill
建立後要驗證觸發是否準確，繼續看啟用流程。
Skill 安全
第三方 Skill 安裝前，要回到 extensions 和安全控制做審查。