google/skills 完整教學 — Google Agent Skills for AI Coding Agents

§1 專案定位與背景

這是什麼？

google/skills 是 Google 官方的 Agent Skills（代理技能） 開源知識庫。它不是傳統的程式庫或框架，而是一組結構化的 Markdown 描述檔（SKILL.md），專門設計給 AI coding agent（如 Gemini CLI、Claude Code、Cursor、Windsurf 等）閱讀，讓 agent 在協助開發者操作 Google Cloud 服務時，能遵循官方最佳實踐、避免常見錯誤、並使用正確的 SDK 與 CLI 指令。

為什麼重要？

AI coding agent 的核心挑戰之一是「幻覺」（hallucination）—— 產生看似正確但實際過時或錯誤的指令。Agent Skills 透過以下機制解決這個問題：

1. 結構化 frontmatter：讓 agent 精準判斷何時該載入哪個 skill
2. 具體的 SDK 範例：避免 agent 推薦已棄用的舊版 SDK（如 google-cloud-aiplatform）
3. 安全護欄（Safety Guardrails）：gcloud skill 內建 denylist，防止 agent 執行危險的刪除或修改指令
4. Helper Scripts：可直接執行的 Python/Bash 腳本，減少 agent 自行生成程式碼的風險

生態系位置

本 repo 是 Agent Skills 生態系 的一部分。Google 同時維護 flutter/skills 和 dart-lang/skills。安裝工具 npx skills 由 skills.sh 提供，支援跨 repo 選擇安裝。

§2 安裝指南

前置需求

• Node.js 18+ 與 npm（用於 npx skills 安裝工具）
• Google Cloud SDK（gcloud）—— 若要使用 cloud 相關 skill
• Python 3.9+（若要執行 helper scripts）
• 已設定 Google Cloud 專案與認證（gcloud auth login）

快速安裝

1# 安裝所有或選擇特定 skill
2npx skills add google/skills
3
4# 安裝過程會列出可選 skill，互動式選擇
5# 選擇後，SKILL.md 會複製到你的專案 .skills/ 目錄

手動安裝（不使用 npx）

1# 直接 clone 整個 repo
2git clone --depth 1 https://github.com/google/skills.git
3
4# 將需要的 skill 目錄複製到你的專案
5cp -r skills/skills/cloud/gemini-api /your-project/.skills/

在不同 AI Agent 中使用

驗證安裝

1# 確認 skill 檔案存在
2ls -la .skills/cloud/gemini-api/SKILL.md
3
4# 測試 gcloud 認證
5gcloud auth list
6gcloud config get project

§3 核心架構解析

整體結構

graph TB
    subgraph "google/skills Repository"
        ROOT["skills/cloud/"]

        subgraph "Agent Platform (13 skills)"
            AP1["gemini-api"]
            AP2["gemini-agents-api"]
            AP3["gemini-interactions-api"]
            AP4["agent-platform-deploy"]
            AP5["agent-platform-inference"]
            AP6["agent-platform-tuning"]
            AP7["agent-platform-eval-flywheel"]
            AP8["agent-platform-skill-registry"]
            AP9["agent-platform-rag-engine-management"]
            AP10["agent-platform-prompt-management"]
            AP11["agent-platform-model-registry"]
            AP12["agent-platform-endpoint-management"]
            AP13["agent-platform-migrate-from-ai-studio"]
        end

        subgraph "Database & Analytics (3)"
            DB1["bigquery-basics"]
            DB2["cloud-sql-basics"]
            DB3["alloydb-basics"]
        end

        subgraph "Infrastructure (3)"
            INFRA1["cloud-run-basics"]
            INFRA2["gke-basics"]
            INFRA3["firebase-basics"]
        end

        subgraph "Recipes (3)"
            RC1["gcloud"]
            RC2["google-cloud-recipe-auth"]
            RC3["google-cloud-recipe-onboarding"]
        end

        subgraph "Well-Architected Framework (6)"
            WAF1["waf-security"]
            WAF2["waf-reliability"]
            WAF3["waf-cost-optimization"]
            WAF4["waf-operational-excellence"]
            WAF5["waf-performance-optimization"]
            WAF6["waf-sustainability"]
        end

        ROOT --> AP1 & DB1 & INFRA1 & RC1 & WAF1
    end

    style ROOT fill:#4285F4,color:#fff
    style AP1 fill:#34A853,color:#fff
    style DB1 fill:#FBBC04,color:#000
    style INFRA1 fill:#EA4335,color:#fff
    style RC1 fill:#9334E6,color:#fff
    style WAF1 fill:#FF6D01,color:#fff

Skill 內部結構

每個 skill 遵循統一的目錄慣例：

 1skills/cloud/<skill-name>/
 2├── SKILL.md              # 必要：核心描述檔
 3│   ├── frontmatter       #   name, description, compatibility
 4│   └── 內容              #   指引、範例、護欄規則
 5├── references/           # 選用：補充參考文件
 6│   ├── core-concepts.md
 7│   ├── cli-usage.md
 8│   ├── client-library-usage.md
 9│   ├── iac-usage.md
10│   └── iam-security.md
11├── scripts/              # 選用：可執行的 Helper Scripts
12│   ├── *.py              #   Python 腳本
13│   └── *.sh              #   Bash 腳本
14└── assets/               # 選用：YAML 範本等靜態資源

SKILL.md Frontmatter 規格

1---
2name: gemini-api                          # 唯一識別名
3description: >-                           # AI agent 用來判斷是否載入的描述
4  Use when the user asks about using
5  Gemini in an enterprise environment...
6compatibility: >-                         # 環境需求
7  Requires active Google Cloud credentials
8  and Agent Platform API enabled.
9---

關鍵設計決策：description 欄位是 skill 的觸發條件。AI agent 根據使用者的提問內容，比對所有已安裝 skill 的 description，選擇最相關的載入。這是一種「被動觸發」模式——skill 不主動執行，而是被 agent 「讀取」後內化為行為指引。

Skill 類別詳解

§4 Helper Scripts 詳細用法

概覽

目前 repo 內含 20 個 helper script（16 Python + 4 Bash），集中在 Agent Platform 系列。

agent-platform-eval-flywheel/scripts/

這是 script 數量最多的 skill（5 個 Python），負責模型評估飛輪工作流。

典型使用流程：

 1# 1. 驗證資料集
 2python scripts/validate_dataset.py --input dataset.json
 3
 4# 2. 執行評估後，解析 trace
 5python scripts/parse_adk_traces.py --trace-dir ./traces/
 6
 7# 3. 檢視單次結果
 8python scripts/inspect_results.py --results eval_results.json
 9
10# 4. 比較多次結果
11python scripts/compare_results.py --baseline v1.json --candidate v2.json
12
13# 5. 生成報告
14python scripts/render_html_report.py --input eval_results.json --output report.html

agent-platform-tuning/scripts/

負責模型調優（Fine-tuning）工作流。

agent-platform-skill-registry/scripts/

agent-platform-deploy/scripts/

agent-platform-inference/scripts/

§5 應用場景

場景 1：Gemini API 企業級整合

情境：你在 Google Cloud 上建構一個 AI 應用，需要呼叫 Gemini API。

載入 skill：gemini-api

關鍵指引：

• 必須使用 Gen AI SDK（google-genai），禁止使用舊版 google-cloud-aiplatform
• 設定環境變數：GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION、GOOGLE_GENAI_USE_ENTERPRISE=true
• 支援 5 種語言：Python / JS/TS / Go / Java / C#

1from google import genai
2
3client = genai.Client()
4response = client.models.generate_content(
5    model="gemini-2.0-flash",
6    contents="Explain quantum computing"
7)
8print(response.text)

場景 2：安全地操作 gcloud CLI

情境：AI agent 協助你執行 gcloud 指令，需要防止危險操作。

載入 skill：gcloud

關鍵指引：

• 內建 denylist 機制，阻擋 delete、destroy、purge 等高風險操作
• 所有指令先 --dry-run 或 --format=json 預覽
• 減少輸出量：使用 --format、--filter、--limit 控制

場景 3：GKE 叢集管理與安全加固

情境：管理 GKE 叢集，需要最佳安全配置。

載入 skill：gke-basics（含 18 份 references + 5 個 YAML assets）

可用 reference：

• gke-security.md：Workload Identity、Network Policy、Pod Security
• gke-scaling.md：HPA / VPA 自動縮放
• gke-golden-path.md：Autopilot 黃金路徑
• gke-inference.md：GPU 推論工作負載

場景 4：模型調優與評估

情境：對 Gemini 或開源模型做 fine-tuning。

載入 skill：agent-platform-tuning + agent-platform-eval-flywheel

工作流：

1. prepare_dataset.py → 格式轉換
2. calculate_cost.py → 預估費用
3. tune_open_model.py → 啟動調優
4. monitor_tuning_job.py → 追蹤進度
5. validate_dataset.py → 驗證評估資料
6. compare_results.py → 對比效果

場景 5：Well-Architected 架構審查

情境：對現有 Google Cloud 架構做全面審查。

載入 skill：6 個 WAF skill

六大支柱：

• 安全（Security）：IAM、加密、網路隔離
• 可靠性（Reliability）：冗餘、災難復原、SLO
• 成本最佳化（Cost Optimization）：資源配置、承諾使用折扣
• 卓越營運（Operational Excellence）：可觀測性、自動化
• 效能最佳化（Performance Optimization）：延遲、吞吐量
• 永續性（Sustainability）：碳排放、能源效率

§6 資安掃描報告

掃描範圍

掃描 skills/ 目錄下所有 145 個檔案，搜尋 eval、exec、os.system、subprocess、shell=True、curl、wget、urlopen、requests、pickle、__import__、secret、token、password、api_key 等敏感模式。

掃描結果

🟢 整體風險等級：低（Low）

無高風險發現（🔴 Critical = 0）

🟡 中等注意項目（Medium = 3）

🟢 低風險項目（Low = 5）

總結

• 無 eval()、exec()、os.system()、subprocess、shell=True、pickle、__import__ 使用
• 無硬編碼憑證：所有 token 均透過 google.auth 動態取得或使用佔位符
• requests 使用安全：僅在 skill_registry_ops.py 中，配合 Google Auth Bearer token
• curl 使用安全：配合 gcloud auth print-access-token，短期 token
• 建議：Cloud SQL 範例可補充 Secret Manager 導引

§7 FAQ

Q1：這和 MCP（Model Context Protocol）有什麼關係？

Agent Skills 和 MCP 是互補的。MCP 定義了 agent 與外部工具互動的協定（function calling），而 Agent Skills 提供的是「知識指引」——告訴 agent 怎麼正確使用這些工具。部分 skill 的 references 目錄中有 mcp-usage.md（如 BigQuery、Cloud SQL、AlloyDB、GKE），說明如何在 MCP 環境中使用該服務。

Q2：可以自己新增 skill 嗎？

目前 Google 不接受外部 PR（見 CONTRIBUTING.md）。但你可以：

• Fork repo 後自行修改
• 在 Issue Tracker 提交 Feature Request
• Google 內部團隊可走 Agent Skills Program 流程

Q3：SKILL.md 的 description 寫法有什麼技巧？

description 是 AI agent 判斷是否載入 skill 的唯一依據。好的寫法應：

• 明確列出觸發關鍵字（如 “Vertex AI”、“Google Cloud”、“Agent Platform”）
• 說明不該觸發的情境（如 “Don’t use when writing client library code”）
• 保持簡潔但具體

Q4：Skill 有版本管理嗎？

目前沒有。Issue #48 有社群討論 versioning 需求，但尚未實作。所有更新透過 main branch 持續交付。建議在專案中 pin 到特定 commit。

Q5：gcloud skill 的 denylist 是什麼？

gcloud skill 內建安全護欄，會在 SKILL.md 中列出 AI agent 不應執行的高風險 gcloud 指令模式（如 delete、destroy），並建議 agent 在執行任何修改性操作前先 dry-run。

Q6：Helper scripts 需要安裝額外依賴嗎？

是的。例如 skill_registry_ops.py 需要 google-auth、requests；prepare_dataset.py 需要 google-cloud-aiplatform。部分 skill 目錄下有 requirements.txt（如 agent-platform-skill-registry/scripts/）。

§8 進階技巧

技巧 1：組合多個 Skill

實務上很少只用一個 skill。以下是常見組合：

技巧 2：自訂觸發邏輯

在你的 AI agent 設定中，可以包裝 skill 的觸發條件：

1# 你的專案 CLAUDE.md
2當使用者提到 Google Cloud、GCP、Gemini、Vertex AI 時：
31. 先載入 skills/cloud/gcloud/SKILL.md
42. 根據具體需求，載入對應的 skill

技巧 3：離線使用與版本鎖定

1# 鎖定到特定 commit
2git clone https://github.com/google/skills.git
3cd skills
4git checkout f072677  # 2026-06-11 版本
5
6# 或用 git submodule
7git submodule add https://github.com/google/skills.git .skills-upstream

技巧 4：搭配 Networking Observability 做成本估算

新增的 google-cloud-networking-observability skill 包含 VPC Flow Logs 成本估算功能，可以幫助你在啟用 flow logs 前預估費用。

技巧 5：善用 References 作為 RAG 來源

每個 skill 的 references/ 目錄可以作為 RAG（Retrieval-Augmented Generation）的知識來源，特別是 GKE 的 18 份 references，涵蓋從叢集建立到推論優化的完整生命週期。

§9 整合進其他工作流

整合到 AIKT（AI-Knowledge Template）

在 AIKT 環境中，google/skills 可以整合為額外的知識層：

1inbox/2026-06-12-github-google-skills.md    ← gh-save 報告（Layer 2）
2inbox/2026-06-12-tutorial-skills.md         ← 本教學（Layer 12 產出）

當使用者詢問 Google Cloud 相關問題時，可先參考這些教學文件，再決定是否需要載入完整的 SKILL.md。

整合到 CI/CD Pipeline

1# GitHub Actions 範例
2- name: Install Google Agent Skills
3  run: |
4    npx skills add google/skills --select gemini-api,gcloud
5    # skill 會安裝到 .skills/ 目錄
6    # AI agent 在 CI 環境中可讀取

搭配 Gemini CLI

1# 安裝 Gemini CLI
2npm install -g @anthropic-ai/gemini-cli  # 假設路徑
3
4# Skills 會自動偵測 .skills/ 目錄
5gemini "help me deploy a Cloud Run service"
6# → agent 會自動載入 cloud-run-basics SKILL.md

作為團隊共享知識

將 skills repo 加入團隊的 monorepo 或共享設定：

1# Git submodule 方式
2git submodule add https://github.com/google/skills.git tools/google-skills
3
4# 或 sparse-checkout 只取需要的 skill
5git clone --filter=blob:none --sparse https://github.com/google/skills.git
6cd skills
7git sparse-checkout set skills/cloud/gemini-api skills/cloud/gcloud

§10 重點摘要 Checklist

安裝與設定

• 確認 Node.js 18+、gcloud CLI 已安裝
• 執行 npx skills add google/skills 選擇需要的 skill
• 確認 Google Cloud 認證（gcloud auth login）
• 設定環境變數（GOOGLE_CLOUD_PROJECT、GOOGLE_CLOUD_LOCATION）

核心概念

• 理解 SKILL.md 的 frontmatter 格式（name / description / compatibility）
• 理解 skill 的「被動觸發」模式：agent 讀取 SKILL.md → 內化為行為指引
• 瞭解 references/ 是補充知識、scripts/ 是可執行工具

Skill 選擇

• AI 應用開發：gemini-api + agent-platform-* 系列
• 基礎建設：gcloud + gke-basics 或 cloud-run-basics
• 資料服務：bigquery-basics、cloud-sql-basics、alloydb-basics
• 架構審查：6 個 waf-* 全部載入
• 新手上路：google-cloud-recipe-onboarding → google-cloud-recipe-auth

安全

• gcloud skill 提供 denylist 護欄
• 無硬編碼憑證（全部使用環境變數或 Google Auth）
• Helper scripts 使用短期 Bearer token
• Cloud SQL 密碼範例應搭配 Secret Manager

維護

• 無正式 release tag，建議 pin commit 或用 submodule
• 追蹤 Issues：GCS / Pub/Sub / Monitoring skill 即將推出
• 不接受外部 PR，透過 Issue Tracker 提供回饋

§11 進一步閱讀

官方資源

• Agent Skills 官網 — 生態系入口
• skills.sh — 安裝工具官網
• google/skills GitHub — 本 repo
• flutter/skills — Flutter Agent Skills
• dart-lang/skills — Dart Agent Skills

Google Cloud 文件

• Gemini API 文件 — Gemini 模型參考
• Agent Platform 文件 — 原 Vertex AI 文件
• gcloud CLI Reference — gcloud 指令參考
• Well-Architected Framework — 架構框架官方文件

相關社群討論

• Issue #37 — 是否作為 Gemini CLI extension 發佈
• Issue #48 — Versioning 討論
• Issue #58 — PII sanitization skill 請求
• Issue #108 — Phantom stars 偵測

Skill 撰寫參考

• CONTRIBUTING.md — 貢獻指引
• SKILL.md 格式 — frontmatter 規格說明
• 範例：skills/cloud/gcloud/SKILL.md（232 行，完整護欄示範）
• 範例：skills/cloud/gemini-interactions-api/SKILL.md（461 行，最大 skill）