分析日期：2026-06-12
数据来源：GitHub 仓库 https://github.com/google/skills
| 项目信息 | 详情 |
|---|---|
| 项目名称 | google/skills |
| 项目地址 | https://github.com/google/skills |
| 项目官网 | https://skills.sh/google/skills |
| 生态平台 | https://agentskills.io |
| 许可证 | Apache 2.0 |
| 总 Star 数 | ~12,300+ |
| 安装量 | 78,000+ |
| 开发状态 | 活跃开发中（Active Development） |
google/skills 是 Google 官方出品 的 AI Agent Skills（代理技能）仓库，为 Claude Code 等 AI 编程代理提供关于 Google 产品和技术（尤其是 Google Cloud）的标准化操作手册。该项目不是面向人类开发者的传统文档，而是专为 AI Agent 设计 的结构化指令集 —— 用 Markdown 编写的、可被 AI Agent 解析和执行的 "操作 SOP"，覆盖从 Gemini API 调用、GCP 产品操作到 Well-Architected 架构评审的全流程。
google/skills
│
├── README.md ← 项目总览 + 安装指南 + Skill 列表
├── LICENSE ← Apache 2.0
│
└── skills/cloud/ ← 所有 Skill 存放目录
│
├── gemini-api/ ← 🔥 核心：Gemini API 使用
│ ├── SKILL.md ← 主指令（frontmatter + 操作指南）
│ └── references/ ← 9个参考文档（文本/多模态/嵌入等）
│ ├── text_and_multimodal.md
│ ├── structured_and_tools.md
│ ├── media_generation.md
│ ├── embeddings.md
│ ├── live_api.md
│ ├── safety.md
│ ├── advanced_features.md
│ ├── model_tuning.md
│ └── bounding_box.md
│
├── gemini-interactions-api/ ← Gemini Interactions API
│ └── SKILL.md
│
├── gemini-agents-api/ ← Managed Agents API
│ └── SKILL.md
│
├── agent-platform-*/ ← 11 个 Agent Platform 管理技能
│ ├── agent-platform-deploy/ ← 部署
│ ├── agent-platform-eval-flywheel/ ← 评估飞轮 ★
│ ├── agent-platform-inference/ ← 推理
│ ├── agent-platform-tuning/ ← 模型微调
│ ├── agent-platform-skill-registry/ ← Skill 注册表
│ └── ... (共 11 个)
│
├── gcloud/ ← gcloud CLI 安全操作指南 ★
│ └── SKILL.md
│
├── *-basics/ ← GCP 产品基础（6个）
│ ├── bigquery-basics/ ← BigQuery
│ ├── cloud-run-basics/ ← Cloud Run
│ ├── cloud-sql-basics/ ← Cloud SQL
│ ├── alloydb-basics/ ← AlloyDB
│ ├── firebase-basics/ ← Firebase
│ └── gke-basics/ ← GKE（含 assets/ 示例 YAML）
│
├── google-cloud-recipe-*/ ← 2 个操作手册
│ ├── google-cloud-recipe-auth/
│ └── google-cloud-recipe-onboarding/
│
├── google-cloud-waf-*/ ← Well-Architected 6 大支柱
│ ├── google-cloud-waf-security/
│ ├── google-cloud-waf-reliability/
│ ├── google-cloud-waf-cost-optimization/
│ ├── google-cloud-waf-operational-excellence/
│ ├── google-cloud-waf-performance-optimization/
│ └── google-cloud-waf-sustainability/
│
└── google-cloud-networking-observability/ ← 网络可观测性
| 项目 | 地址 |
|---|---|
| Flutter Skills | https://github.com/flutter/skills |
| Dart Skills | https://github.com/dart-lang/skills |
| Anthropic Agent Skills 规范 | https://agentskills.io/home |
在 Google 长期缺乏官方 AI Agent 工具链接口的背景下，google/skills 的发布标志着 Google 首次以 标准化、结构化 的方式将其云产品知识编码为 AI Agent 可消费的格式。这不是传统的 API 文档，而是一套让 AI Agent "学会正确使用 Google 产品" 的 操作范本。
该项目核心设计哲学：每一份 SKILL.md 都是一段 给 AI Agent 的系统提示词，用 Markdown frontmatter 标注元数据（名称、描述、兼容性），用结构化 Markdown 提供分步操作指南。Agent 加载后立即获得对应 Google 产品的 "专家级操作能力"，无需从零摸索。
每个 Skill 采用 三级知识加载 机制，类似 CPU 缓存分层：
| 层级 | 文件 | 作用 | 类比 |
|---|---|---|---|
| L1 | SKILL.md |
核心指令 + 快速启动 + 索引 | 操作手册首页 |
| L2 | references/*.md |
细分专题详细文档 | 操作手册附录 |
| L3 | scripts/*.py/.sh |
可执行自动化脚本 | 工具箱 |
Agent 默认加载 L1（控制上下文消耗），按需深入 L2/L3 —— 既保证了效率，也保证了深度。
通过 npx skills add google/skills 一行命令完成安装，安装时可 按需勾选 具体 Skill，避免全量下载。这不是简单的 Git clone，而是 skills.sh 协议下的标准化分发机制，支持 Agent 动态拉取和热加载。
gcloud Skill 是一个教科书级别的 AI Agent 安全设计案例：
gcloud help 验证命令合法性，防止幻觉命令--format + --limit + --filter 三层过滤，防止上下文溢出--quiet，避免等待用户输入30+ 个 Skill 覆盖 Gemini 三大 API、6 大 GCP 核心产品、Agent Platform 完整管理链路、Well-Architected Framework 六大支柱，形成从 "AI 模型调用 → 基础设施管理 → 架构评审" 的完整能力闭环。
| 条件 | 说明 |
|---|---|
| Agent 平台 | 需支持 Agent Skills 协议（如 Claude Code、Anthropic Agent SDK） |
| 安装工具 | Node.js 环境（用于 npx skills 命令） |
| 文件系统访问 | Agent 需能读取本地 Skill 文件 |
不同 Skill 对运行环境有不同要求：
| Skill 分类 | 环境依赖 | 说明 |
|---|---|---|
| Gemini API 类 | Google Cloud 项目 + API 密钥或 ADC 认证 | 需 GOOGLE_CLOUD_PROJECT + GOOGLE_CLOUD_LOCATION 环境变量 |
| Agent Platform 类 | Google Cloud 项目 + 对应 API 启用 | pip install google-genai / google-cloud-aiplatform[evaluation] |
| gcloud CLI 类 | 本地安装 gcloud CLI | 需认证登录（用户账户 / 服务账户） |
| GCP 产品类 | 对应 GCP 服务启用 + 相应 SDK/CLI | 如 BigQuery 需 bq 工具，Cloud SQL 需客户端库 |
| WAF 评审类 | 无特殊依赖 | 纯知识指导，用于架构评审建议生成 |
| 语言 | 包名 | 安装命令 |
|---|---|---|
| Python | google-genai |
pip install google-genai |
| JavaScript/TypeScript | @google/genai |
npm install @google/genai |
| Go | google.golang.org/genai |
go get google.golang.org/genai |
| Java | com.google.genai:google-genai |
Gradle / Maven |
| C#/.NET | Google.GenAI |
dotnet add package Google.GenAI |
⚠️ 重要：旧版 SDK（
google-cloud-aiplatform、@google-cloud/vertexai、google-generativeai）已弃用，Skill 明确禁止 Agent 使用。
# 方式一：Application Default Credentials (ADC) - 推荐
export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='global'
export GOOGLE_GENAI_USE_ENTERPRISE=true
# 方式二：Express Mode (API Key)
export GOOGLE_API_KEY='your-api-key'
export GOOGLE_GENAI_USE_ENTERPRISE=true
google/skills 的核心架构是一个 "知识编码系统"，而非传统软件系统：
┌─────────────────────────────────────────────────────┐
│ skills.sh 协议层 │
│ npx skills add → 拉取 → 解析 → 按需安装 │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ Skill 文件层 (SKILL.md) │
│ ┌─────────────┐ ┌─────────────┐ ┌─────────────┐ │
│ │ Frontmatter │ │ 核心指令区 │ │ 参考索引区 │ │
│ │ (name,desc) │ │ (操作SOP) │ │ (references)│ │
│ └─────────────┘ └─────────────┘ └─────────────┘ │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ 参考文档层 (references/*.md) │
│ API 规范 · SDK 用法 · IaC 模板 · 安全策略 · MCP 集成 │
└──────────────────────┬──────────────────────────────┘
│
┌──────────────────────▼──────────────────────────────┐
│ 脚本工具层 (scripts/*.py) │
│ 自动化操作 · 数据验证 · 结果渲染 · 差异对比 │
└─────────────────────────────────────────────────────┘
每个 Skill 的 SKILL.md 遵循以下标准结构：
---
name: skill-name # 机器可读标识
description: >- # 触发条件 + 能力描述
用于 Agent 决策 "何时加载此 Skill"
包含关键词触发词（如 "BigQuery", "SQL", "数据分析"）
compatibility: ... # 可选：兼容性声明
---
# 标题
## Setup and Basic Usage # 快速启动（最小可行步骤）
## Core Directives # 核心指令（Agent 必须遵守的规则）
## Models / Configuration # 模型/配置参考
## Quick Start # 各语言快速启动代码
## Reference Directory # 参考文档索引（按需加载入口）
## Related Skills # 关联 Skill 引用
核心设计理念：
description 字段中的关键词判断何时加载该 Skill这是整个仓库中设计最精良的 Skill，体现了 "AI Agent 安全操作" 的最佳实践：
2.1 命令验证（防幻觉）
必须验证 → 必须验证 → 才能执行
│ │ │
gcloud help → 确认语法 → 执行命令
命令 正确
gcloud help <command> 验证命令、标志、参数值、位置参数语法2.2 数据减少三件套
# 1. 投影：只取需要的字段
gcloud compute instances list --format="json(name, zone, status)"
# 2. 限制：控制返回数量
gcloud compute instances list --limit=10
# 3. 过滤：服务端筛选
gcloud compute instances list --filter="status:RUNNING"
2.3 操作黑名单（Denylist）
| 禁止操作 | 风险类型 | 原因 |
|---|---|---|
| IAM 策略/角色/绑定修改 | 安全 | 权限提升、管理锁定、服务中断 |
| API 主动启用 | 资源/计费 | 意外资源创建和费用 |
gcloud * delete |
破坏性 | 不可逆资源销毁 |
gcloud billing * |
财务 | 服务中断或无界成本 |
gcloud organizations * |
治理 | 组织级安全策略变更 |
gcloud kms * |
加密 | 永久数据锁定风险 |
2.4 执行约束
--quiet 非交互模式--async这是仓库中最复杂的 Skill，实现了完整的 AI Agent 质量提升循环：
┌──────────────────────────────────┐
│ Quality Flywheel │
│ │
│ 1. Prepare ──→ 2. Run Inference │
│ ↑ │ │
│ │ ↓ │
│ 5. Optimize ←── 3. Grade │
│ ↑ │ │
│ └──── 4. Analyze ←───────────┘
│ │
└──────────────────────────────────┘
评估指标体系（13 项内置指标）：
| 指标类别 | 指标名 | 用途 |
|---|---|---|
| Agent 多轮 | multi_turn_task_success |
任务完成度 |
multi_turn_trajectory_quality |
推理路径质量 | |
multi_turn_tool_use_quality |
工具调用质量 | |
multi_turn_general_quality |
对话整体质量 | |
| 响应质量 | final_response_quality |
最终回复质量 |
final_response_match |
与黄金标准匹配度 | |
| 单轮工具 | tool_use_quality |
单轮工具使用质量 |
| 通用质量 | general_quality |
整体回复质量 |
text_quality |
语言质量 | |
instruction_following |
指令遵循度 | |
| 固定标准 | hallucination |
幻觉检测 |
grounding |
上下文一致性 | |
safety |
安全合规 |
失败诊断映射表（核心价值）：
每个指标低分都有明确的 "如何修复" 指引，例如：
hallucination 低 → "加强对工具输出的引用；验证工具是否真正返回了声称的数据"instruction_following 低 → "在系统指令中用更严格的措辞重申约束"multi_turn_task_success 低 → "修复编排、缺失工具调用、过早终止、错误工具选择"错误聚类分析：10+ 失败案例时，自动调用 generate_loss_clusters 服务将失败聚合为 L1/L2 分类主题。
该 Skill 展示了如何将 API 文档转化为 Agent 可执行的操作指令：
模型选择指令（硬编码推荐）：
- 用 `gemini-3.1-pro-preview` 处理复杂推理、编码、研究（1M tokens）
- 用 `gemini-3.5-flash` 处理快速、均衡性能的多模态场景（1M tokens）
- 用 `gemini-3.1-flash-lite` 处理高频、轻量任务（1M tokens）
SDK 统一策略（防止 Agent 选错库）：
ALWAYS use the Gen AI SDK (`google-genai`)
DO NOT use `google-cloud-aiplatform`, `@google-cloud/vertexai`, `google-generativeai`
参考文档按功能域组织（9 大分类）：
BigQuery、Cloud Run、Cloud SQL、AlloyDB、Firebase、GKE 六个产品 Skill 共享统一的 六维参考框架：
| 维度 | 参考文件 | 内容 |
|---|---|---|
| 核心概念 | core-concepts.md |
产品架构、定价、区域可用性 |
| CLI 操作 | cli-usage.md |
命令行工具基础操作 |
| 客户端库 | client-library-usage.md |
Python/Java/Node.js/Go SDK |
| MCP 集成 | mcp-usage.md |
通过 MCP 协议集成 |
| IaC 管理 | iac-usage.md |
Terraform 模板 |
| 安全与权限 | iam-security.md |
角色、权限、数据治理 |
这种一致性设计确保 Agent 无论处理哪个 GCP 产品，都能预期相同的知识结构。
六大支柱 Skill，每个都是纯知识指导型，用于 Agent 进行 GCP 架构评审：
安全性 → 可靠性 → 成本优化 → 卓越运营 → 性能优化 → 可持续性
# Python - 最简客户端初始化
from google import genai
client = genai.Client() # 自动从环境变量读取配置
response = client.models.generate_content(
model="gemini-3.5-flash",
contents="Explain quantum computing",
)
print(response.text)
// TypeScript - 企业模式初始化
import { GoogleGenAI } from "@google/genai";
const ai = new GoogleGenAI({
enterprise: { project: "your-project-id", location: "global" }
});
const response = await ai.models.generateContent({
model: "gemini-3.5-flash",
contents: "Explain quantum computing"
});
console.log(response.text);
设计亮点：Python 版支持零参数初始化（环境变量自动注入），TypeScript 版支持企业模式配置，两者都被精心设计为 Agent 可直接复制执行的 "即用代码"。
import agentplatform
from agentplatform import types
# 初始化
client = agentplatform.Client(project="PROJECT_ID", location="global")
# 准备数据集（支持 EvalCase 列表 / DataFrame / 合成生成 三种输入）
dataset = types.EvaluationDataset(eval_cases=[
types.EvalCase(prompt="What is 2+2?", response="4", reference="4"),
])
# 运行评估
result = client.evals.evaluate(
dataset=dataset,
metrics=[types.RubricMetric.MULTI_TURN_TRAJECTORY_QUALITY]
)
# 读取结果（不允许编造 → 必须从 result 对象读取）
for s in result.summary_metrics:
print(f"{s.metric_name}: mean={s.mean_score}, pass_rate={s.pass_rate}")
设计亮点：Skill 中强调 "Proving your work" 原则 —— Agent 不能声称评估结果，必须从实际 SDK 返回的 result 对象中读取并展示 summary_metrics。
# ❌ 错误：Agent 直接凭记忆执行
gcloud compute instances create my-vm --zone=us-central1-a
# ✅ 正确：先验证 → 再 dry-run → 最后执行
# Step 1: 验证命令存在且语法正确
gcloud help compute instances create
# Step 2: Dry-run 预览
gcloud compute instances create my-vm \
--zone=us-central1-a \
--project=my-project \
--dry-run
# Step 3: 确认后执行（带完整参数）
gcloud compute instances create my-vm \
--zone=us-central1-a \
--project=my-project \
--quiet
开发者在 Claude Code 中安装 google/skills 后，Agent 获得 Google Cloud 全产品线的正确操作知识，可直接执行：
企业开发者使用 Eval Flywheel Skill 构建 Agent 质量飞轮：
大型企业的 Cloud Center of Excellence 团队：
通过 gcloud Skill 的设计模式，展示如何构建安全的 AI Agent 操作系统：
开发者利用 Gemini API Skill 中丰富的代码示例和参考文档：
| 优点 | 说明 |
|---|---|
| 权威性 | Google 官方出品，与 Google Cloud 产品团队同步更新，杜绝第三方文档的过时问题 |
| 标准化 | 遵循 Agent Skills 生态规范（agentskills.io），跨 Agent 平台通用 |
| 安全性 | gcloud Skill 的安全设计堪称 AI Agent 操作系统的教科书级实现 |
| 渐进式深度 | 三级知识加载（SKILL.md → references → scripts），兼顾效率和深度 |
| 多语言覆盖 | Gemini API Skill 覆盖 Python/JS/Go/Java/C# 五种主流语言 |
| 按需安装 | npx skills add 支持勾选安装，不浪费 Agent 上下文窗口 |
| 可执行性 | 代码示例均为可直接复制执行的完整代码，非伪代码 |
| 失败诊断闭环 | Eval Flywheel 提供 "指标低分 → 诊断原因 → 修复建议" 的完整链路 |
| 生态联动 | 关联 Flutter Skills、Dart Skills，形成 Google 技术栈全覆盖 |
| 不足 | 说明 | 改进建议 |
|---|---|---|
| Google Cloud 偏向严重 | 30+ 个 Skill 几乎全部面向 Google Cloud，缺少对 Google Workspace（Gmail、Docs、Sheets）等办公产品的覆盖 | 增加 Workspace 系列 Skill（如 Gmail API、Google Sheets API） |
| 无中文版本 | 所有 Skill 均为纯英文，对中文环境的 Agent 不够友好（部分技术术语 Agent 翻译可能不准确） | 提供多语言 Skill 版本或国际化机制 |
| 版本管理缺失 | 仓库 README 标注 "主动开发中"，但无版本号或 changelog，Agent 无法判断 Skill 是否过时 | 引入 SemVer 版本管理 + 更新日志 |
| 新增 Skill 门槛高 | CONTRIBUTING.md 缺失，外部贡献者不清楚如何提交新 Skill | 补充完整的贡献指南和 Skill 编写模板 |
| 安装依赖 Node.js | npx skills 强制依赖 Node.js，纯 Python 环境的 Agent 无法使用 |
提供 pip install 或直接 git clone 的替代安装路径 |
| 测试覆盖不可见 | 无可见的 CI/CD 配置或 Skill 正确性验证流程 | 增加自动化测试（如 Skill 代码示例的可运行性验证） |
| 隐私/安全 Skill 较薄 | 安全和隐私主题仅分散在各产品 Skill 中，没有独立的 Security/Privacy 综合 Skill | 创建 google-cloud-security-posture 等综合性安全 Skill |
| 离线使用支持不足 | npx skills 需要网络，无离线缓存机制 |
支持本地 Skill 缓存和离线安装模式 |
| 序号 | Skill 名称 | 说明 |
|---|---|---|
| 1 | gemini-api | Gemini 多模态 API 完整指南 |
| 2 | gemini-interactions-api | Gemini 交互式 API |
| 3 | gemini-agents-api | Managed Agents API |
| 序号 | Skill 名称 | 说明 |
|---|---|---|
| 4 | agent-platform-deploy | Agent 部署指南 |
| 5 | agent-platform-endpoint-management | 端点管理 |
| 6 | agent-platform-eval-flywheel | 质量评估飞轮 ★ |
| 7 | agent-platform-inference | 推理调用 |
| 8 | agent-platform-migrate-from-ai-studio | 从 AI Studio 迁移 |
| 9 | agent-platform-model-registry | 模型注册表 |
| 10 | agent-platform-prompt-management | 提示词管理 |
| 11 | agent-platform-rag-engine-management | RAG 引擎管理 |
| 12 | agent-platform-skill-registry | Skill 注册表 |
| 13 | agent-platform-tuning | 模型微调 |
| 14 | agent-platform-tuning-management | 微调任务管理 |
| 序号 | Skill 名称 | 说明 |
|---|---|---|
| 15 | bigquery-basics | BigQuery 数据分析平台 |
| 16 | cloud-run-basics | Cloud Run 无服务器容器 |
| 17 | cloud-sql-basics | Cloud SQL 托管数据库 |
| 18 | alloydb-basics | AlloyDB PostgreSQL |
| 19 | firebase-basics | Firebase 应用平台 |
| 20 | gke-basics | GKE Kubernetes 引擎 |
| 序号 | Skill 名称 | 说明 |
|---|---|---|
| 21 | gcloud | gcloud CLI 安全操作 ★ |
| 22 | google-cloud-recipe-onboarding | GCP 上手指南 |
| 23 | google-cloud-recipe-auth | GCP 认证指南 |
| 序号 | Skill 名称 | 说明 |
|---|---|---|
| 24 | google-cloud-waf-security | 安全支柱 |
| 25 | google-cloud-waf-reliability | 可靠性支柱 |
| 26 | google-cloud-waf-cost-optimization | 成本优化支柱 |
| 27 | google-cloud-waf-operational-excellence | 卓越运营支柱 |
| 28 | google-cloud-waf-performance-optimization | 性能优化支柱 |
| 29 | google-cloud-waf-sustainability | 可持续性支柱 |
| 序号 | Skill 名称 | 说明 |
|---|---|---|
| 30 | google-cloud-networking-observability | 网络可观测性分析 |
📝 分析说明：本项目分析基于 2026-06-12 的仓库快照，代码架构与 Skill 结构以实际克隆的源码为准。项目处于活跃开发状态，后续版本可能有所变化。
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。