---
title: "建立 Skills"
description: "Gemini CLI 建立 Agent Skill 的判斷標準：什麼時候應該沉澱、結構如何保持小、如何避免把一次性任務過度工程化。"
verifiedAt: "2026-05-09"
---

建立 Skill 的前提不是“這個功能很酷”，而是“這個任務會重複出現，而且每次都需要同一套步驟和約束”。

> [!IMPORTANT]
> 先跑通流程，再沉澱 Skill。沒驗證過的流程寫進 Skill，只會把一次性混亂變成長期混亂。

## 建立前檢查

| 問題 | 如果答案是 no |
| --- | --- |
| 這個任務會重複嗎 | 不要建 skill |
| 流程已經跑透過嗎 | 先手工跑一次 |
| 輸入輸出能固定嗎 | 先整理契約 |
| 風險邊界清楚嗎 | 先補安全說明 |
| 比 custom command 更復雜嗎 | 簡單任務用 custom command |

## 推薦目錄

`SKILL.md` 是唯一必需檔案，但真實 Skill 通常需要把確定性部分拆出來：

```text
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` 是觸發器，必須寫“什麼時候用”，而不是泛泛描述能力。

```markdown
---
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` 才算寫對。

## 接下來去哪

<Cards>
  <Card title="Skills 最佳實踐" description="繼續看 description、上下文層級、指令碼和失敗路徑怎麼設計。" href="/zh-Hant/docs/gemini-cli/official/04-agents-skills/42-skills-best-practices" />
  <Card title="啟用 Skill" description="建立後要驗證觸發是否準確，繼續看啟用流程。" href="/zh-Hant/docs/gemini-cli/official/04-agents-skills/43-activate-skill" />
  <Card title="Skill 安全" description="第三方 Skill 安裝前，要回到 extensions 和安全控制做審查。" href="/zh-Hant/docs/gemini-cli/official/03-tools-mcp/38-extensions" />
</Cards>

## 官方來源

- [Creating Agent Skills](https://github.com/google-gemini/gemini-cli/blob/main/docs/cli/creating-skills.md)
