Gemini CLI Extensions 實戰指南：從零打造你的 AI 擴充功能

為什麼你需要 Gemini CLI Extensions？

你是否曾經想過：

• 「如果我可以把自己常用的那串落落長的 Prompt 變成一個簡單的指令...」
• 「如果 AI 可以直接讀取我公司的內部 API 文檔...」
• 「如果我可以把這一整套工作流打包分享給同事...」

Gemini CLI Extensions 正是為了這些需求而生。它是一個開源框架，讓你能夠客製化 Gemini CLI，將 Prompt Engineering (提示工程)、MCP Servers (工具整合) 和 Context (知識庫) 打包成一個可攜式、易安裝、易分享的標準化模組。

根據 官方文檔，Extensions 的核心優勢包括：

• 一鍵安裝：透過 GitHub URL 或本地路徑即可安裝
• 版本控制：支援 SemVer 版本管理
• 衝突解決：自動處理命令名稱衝突
• 企業就緒：可建立團隊專屬的工具平台

在這篇教學中，我們將一起動手做一個簡單但實用的擴充功能："Team Standup Helper"，它能幫助你整理每日站會進度。

第一步：建立專案結構

Gemini CLI Extension 的本質就是一個特定的資料夾結構。讓我們開始吧：

mkdir my-standup-extension
cd my-standup-extension
mkdir commands

一個標準的 Extension 結構如下：

my-standup-extension/
├── gemini-extension.json   # [必要] 設定檔
├── GEMINI.md               # [選用] 上下文 (Context)，預設名稱
└── commands/               # [選用] 自訂指令
    └── standup.toml

第二步：定義設定檔 (gemini-extension.json)

這是擴充功能的身分證。在根目錄建立 gemini-extension.json：

{
  "name": "team-standup-helper",
  "version": "1.0.0",
  "description": "協助團隊快速生成站會報告並檢查 GitHub Issue 狀態",
  "mcpServers": {
    "github-mcp": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-github"]
    }
  },
  "contextFileName": "GEMINI.md",
  "excludeTools": ["run_shell_command"]
}

設定檔完整說明

進階設定：excludeTools 的精細控制

你可以更精確地控制要禁用的指令：

{
  "excludeTools": [
    "run_shell_command",
    "run_shell_command(rm -rf)",
    "run_shell_command(sudo *)"
  ]
}

第三步：注入靈魂 - 上下文 (GEMINI.md)

GEMINI.md 是你告訴 AI "你是誰" 以及 "你該怎麼做" 的地方。這比每次貼上一大段 Prompt 有效得多。

建立 GEMINI.md：

# Role

你是一位敏捷開發團隊的 Scrum Master 助理。你的目標是協助團隊成員整理每日站會 (Daily Standup) 的內容。

# Rules

1. 輸出格式必須包含：
   - **昨日完成**: (列出已 Close 的 Issue)
   - **今日計畫**: (列出正在進行中的 Issue)
   - **阻礙**: (分析標記為 'blocked' 的 Issue)
2. 語氣要專業但輕鬆，鼓勵團隊士氣。
3. 嚴格遵守 Markdown 格式。
4. 如果找不到 Issue 資料，請禮貌地請使用者確認 GitHub 權限設定。

第四步：建立自訂指令 (commands/standup.toml)

現在我們將這個能力封裝成一個簡單的指令 /standup。

在 commands/standup.toml 中寫入：

description = "生成每日站會報告"

content = """
請根據我目前在 GitHub 上指派給我的 Issues，幫我草擬一份今天的站會報告。
請特別關注 'bug' 標籤的 Issue。
我的 GitHub username 是: {{USER_INPUT}}
"""

自訂指令的命名規則

• 檔名就是指令名稱（不含 .toml）
• 可以用子目錄建立命名空間：commands/gcs/sync.toml → /gcs:sync
• 指令名稱會自動加上 Extension 前綴以避免衝突

第五步：本地測試與安裝

開發完成後，我們不需要急著發布，可以先用 link 指令在本地測試：

# 在擴充功能目錄下執行
gemini extensions link .

你也可以使用模板快速建立新的 Extension：

# 建立一個新的 Extension 樣板
gemini extensions create my-new-extension

現在，打開你的 Gemini CLI，你可以直接使用：

/standup my-github-username

AI 就會自動調用我們設定好的 GitHub MCP，去抓取你的 Issue 狀態，並根據 GEMINI.md 的規則，生成一份完美的站會報告！

Extension 管理指令總覽

進階功能：Extension Settings (實驗性)

Extensions 可以定義使用者需要在安裝時提供的設定值，例如 API Keys：

{
  "name": "my-api-extension",
  "version": "1.0.0",
  "settings": [
    {
      "name": "API Key",
      "description": "Your API key for the service.",
      "envVar": "MY_API_KEY",
      "sensitive": true
    }
  ]
}

當使用者安裝時，會被提示輸入這個設定值。設定值會被安全地儲存在 Extension 目錄下的 .env 檔案中。

進階技巧：如何發布給全世界？

當你對你的作品感到滿意，發布流程非常簡單：

1. Push 到 GitHub: 將整個資料夾推送到一個公開的 Repository。
2. Tag Release: 建議使用 SemVer (如 v1.0.0)。
3. 分享安裝連結: 其他人只需一行指令即可安裝：

gemini extensions install https://github.com/your-username/my-standup-extension

命令衝突解決機制

如果你的 Extension 指令與使用者自訂指令重名，系統會自動處理：

• 無衝突時：使用原始名稱，如 /standup
• 有衝突時：自動加上 Extension 前綴，如 /team-standup-helper.standup

使用者的指令永遠優先於 Extension 指令。

延伸閱讀

• Gemini CLI Extensions 官方文檔
• Extension 開發入門指南
• Extension 發布指南
• Extension Gallery - 瀏覽現有的 Extensions
• Model Context Protocol 官方文檔

總結

Gemini CLI Extensions 讓「客製化 AI」變得前所未有的簡單。你不需要是 AI 專家，只需要懂得定義問題和整理知識，就能打造出強大的工具。

現在，試著看看你的工作流，有哪些重複性的任務可以被封裝成一個 Extension 呢？