Google Agent Skills 全解析：AI Agent 的标准化技能框架

TextMatrix 收录于技术笔记

2026-04-25 约 6076 字预计阅读 16 分钟

Google Agent Skills 全解析：AI Agent 的标准化技能框架

目标读者：AI Agent 开发者、云架构师、Google Cloud 用户 核心问题：如何让 AI Agent 具备可复用、可审计的专业技能知识？难度：⭐⭐⭐⭐ 类型：专家设计 预计阅读时间：25 分钟

🎯 问题背景：AI Agent 的知识困境

AI Agent 开发的核心挑战

在构建专业 AI Agent 时，开发者常常面临一个困境：

知识碎片化：产品特性分散在官网、博客、论坛、社区，来回切换效率低下
上下文膨胀：把所有文档都塞进 prompt 会导致 token 爆表，响应变慢
一致性缺失：不同开发者、不同场景下，调用方式各不相同，难以审计
版本同步困难：产品 API 更新后，本地知识库容易过时

传统方案的局限

方案	问题
把所有文档塞进 RAG	上下文膨胀，检索质量下降
依赖模型训练获得知识	成本高、更新慢、难以精确控制
分散的博客/论坛查询	权威性低、格式不统一、难以自动化
每个项目维护一套文档	重复劳动、知识孤岛、难以复用

Google Agent Skills 的破局思路

Google Agent Skills 的核心思路是：把专业技能封装成标准化的可复用单元，让 Agent 按需加载、精确调用。

📝 核心概念：SKILL.md 格式详解

技能文件结构

每个技能的核心是一个 SKILL.md 文件，采用 frontmatter + Markdown 的结构：

---
name: gemini-api
description: Guides the usage of the Gemini API on Agent Platform...
compatibility: Requires active Google Cloud credentials...
---

# Gemini API in Agent Platform

## Core Directives
- **Unified SDK**: ALWAYS use the Gen AI SDK...

## SDKs
- **Python**: `pip install google-genai`
- **JavaScript/TypeScript**: `npm install @google/genai`

## Quick Start
...代码示例...

Frontmatter 字段说明

字段	必填	说明
`name`	✅	技能唯一标识符
`description`	✅	使用场景描述，告诉 Agent 何时该激活此技能
`compatibility`	❌	兼容性要求或前置依赖
`license`	❌	许可证类型
`metadata`	❌	作者、版本等元数据

Description 的触发机制

description 字段是技能激活的关键。当用户请求匹配描述时，Agent 会激活对应技能：

description: "Use when the user asks about using Gemini in an enterprise 
environment or explicitly mentions Vertex AI, Google Cloud, or Agent Platform."

这个描述会被 Agent 解析，用于判断是否需要激活该技能。

核心指令区（Core Directives）

Core Directives 是技能的硬性规则，Agent 必须遵守：

## Core Directives

- **Unified SDK**: ALWAYS use the Gen AI SDK (`google-genai` for Python...)
- **Legacy SDKs**: DO NOT use `google-cloud-aiplatform` or `@google-cloud/vertexai`

这些指令确保 Agent 总是使用最新、最推荐的方式工作。

🔄 渐进式加载：避免上下文膨胀

核心设计思想

传统的 RAG 会一次性加载所有相关文档，导致：

上下文窗口被大量低相关度内容占据
检索质量随文档库增大而下降
Token 成本急剧上升

Google Agent Skills 采用按需渐进式加载：

首层匹配：根据用户请求，匹配最相关的技能（通过 description）
技能激活：仅加载该技能的 SKILL.md 主文件
按需加载：如果任务需要，再加载对应的 reference 参考文档

参考文档系统

每个技能目录下有一个 references/ 文件夹，包含更详细的专项文档：

skills/cloud/gke-basics/
├── SKILL.md                    # 技能主文件
└── references/
    ├── core-concepts.md       # 核心概念
    ├── gke-golden-path.md     # 最佳实践路径
    ├── gke-cluster-creation.md # 集群创建
    ├── gke-networking.md      # 网络配置
    ├── gke-security.md        # 安全加固
    └── ...                     # 更多专项文档

触发词机制

SKILL.md 中会定义触发词到参考文档的映射：

| Scenario | Trigger Keywords | Reference |
|----------|-----------------|-----------|
| Core Concepts | Autopilot vs Standard, architecture | [core-concepts.md](...) |
| Networking | private cluster, VPC, subnet | [gke-networking.md](...) |
| Security | Workload Identity, RBAC, hardening | [gke-security.md](...) |

Agent 根据用户的具体请求关键词，选择性加载对应的参考文档。

🏗️ 架构设计：跨平台兼容

一次构建，多端运行

Google Agent Skills 的设计目标是一次编写，兼容所有主流 Agent 平台：

skills/
└── cloud/
    └── gke-basics/           # 技能定义（通用）
        ├── SKILL.md
        └── references/

# 兼容的 Agent 平台：
# - Antigravity
# - Gemini CLI
# - Google ADK (Agent Development Kit)
# - 任何支持 SKILL.md 格式的 Agent

安装方式

通过 skills.sh 工具一键安装：

# 安装整个技能库
npx skills add google/skills

# 从技能库中选择性安装特定技能
npx skills add google/skills/gke-basics
npx skills add google/skills/bigquery-basics

与 MCP 的对比

特性	Google Agent Skills	MCP (Model Context Protocol)
定位	知识与工作流封装	工具与资源调用
核心文件	SKILL.md + references/	tools.mcp.json
触发方式	描述匹配	函数调用
内容形式	指令 + 代码示例 + 文档	API schema + 工具定义
适用场景	需要深度知识的场景	需要调用外部工具的场景
更新方式	仓库同步	运行时发现

两者可以互补：Agent Skills 提供知识，MCP 提供工具能力。

📦 可用技能一览

Google Cloud 基础技能

技能	说明	核心能力
Gemini API	Agent Platform 上的 Gemini 使用指南	SDK、认证、多模态、Live API
BigQuery Basics	数据仓库基础操作	SQL 查询、数据集管理、BigQuery ML
Cloud Run Basics	Serverless 容器运行平台	部署、扩缩容、金丝雀发布
Cloud SQL Basics	全托管数据库服务	MySQL/PostgreSQL 配置、备份、复制
GKE Basics	Kubernetes 管理平台	集群创建、网络、安全、成本优化
AlloyDB Basics	PostgreSQL 兼容数据库	高可用、自动扩容、零运维
Firebase Basics	移动/Web 开发平台	认证、Firestore、Cloud Functions

配方技能（Recipes）

配方技能封装了多步骤的工作流程：

技能	说明
Onboarding Recipe	Google Cloud 新账号初始化检查清单
Auth Recipe	Google Cloud 认证配置最佳实践
Network Observability Recipe	网络可观测性配置

架构框架技能

基于 Google Cloud Well-Architected Framework 的专项指导：

技能	关注领域
WAF Security	安全 pillar：身份认证、数据保护、合规
WAF Reliability	可靠性 pillar：SLA、灾备、监控
WAF Cost Optimization	成本优化：资源.rightsizing、承诺使用、预算告警

💻 代码示例：Gemini API 实战

Python 快速开始

from google import genai
client = genai.Client()

response = client.models.generate_content(
    model="gemini-3-flash-preview",
    contents="Explain quantum computing"
)
print(response.text)

多语言 SDK 支持

语言	包名	安装命令
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`	Maven/Gradle 配置
C#/.NET	`Google.GenAI`	`dotnet add package Google.GenAI`

认证配置

方式一：应用默认凭证（ADC）

export GOOGLE_CLOUD_PROJECT='your-project-id'
export GOOGLE_CLOUD_LOCATION='global'
export GOOGLE_GENAI_USE_VERTEXAI=true

from google import genai
client = genai.Client()  # 自动读取环境变量

方式二：API Key（Express Mode）

export GOOGLE_API_KEY='your-api-key'
export GOOGLE_GENAI_USE_VERTEXAI=true

🗂️ 参考文档系统详解

GKE 技能参考文档映射

以 GKE Basics 为例，展示完整的参考文档架构：

| 场景 | 触发关键词 | 参考文档 |
|------|-----------|---------|
| 核心概念 | Autopilot vs Standard, architecture | core-concepts.md |
| 黄金路径 | golden path, Day-0 checklist | gke-golden-path.md |
| 集群创建 | create cluster, new cluster | gke-cluster-creation.md |
| 网络配置 | private cluster, VPC, subnet | gke-networking.md |
| 安全加固 | Workload Identity, RBAC | gke-security.md |
| 扩缩容 | HPA, VPA, autoscaler | gke-scaling.md |
| 成本优化 | cost, savings, Spot VMs | gke-cost.md |
| AI/ML 推理 | inference, model serving, GPU | gke-inference.md |
| 可观测性 | monitoring, Prometheus | gke-observability.md |
| 多租户 | multi-tenant, namespace | gke-multitenancy.md |

BigQuery 参考文档结构

bigquery-basics/
├── SKILL.md
└── references/
    ├── core-concepts.md           # 存储类型、分析工作流
    ├── cli-usage.md               # bq 命令行工具
    ├── client-library-usage.md    # Python/Java/Node.js/Go 客户端
    ├── mcp-usage.md               # MCP 服务器使用
    ├── iac-usage.md               # Terraform IaC 示例
    └── iam-security.md            # IAM 角色与权限

🔧 高级特性

配方技能的工作流封装

配方技能将复杂的多步骤任务封装成可执行的检查清单：

# Recipe: Google Cloud Onboarding

## Day-0 检查清单

- [ ] 创建 Google Cloud 项目
- [ ] 启用计费账户
- [ ] 配置初始 IAM 角色
- [ ] 设置组织策略
- [ ] 配置审计日志
...

版本迁移指导

技能中包含明确的版本迁移路径，避免使用已废弃的 API：

> [!WARNING]
> Legacy SDKs like `google-cloud-aiplatform`, `@google-cloud/vertexai` 
> are deprecated. Migrate to the new SDKs above urgently.

模型推荐机制

技能中定义了当前推荐的模型列表，帮助 Agent 始终使用最新最优的模型：

## Models

- Use `gemini-3.1-pro-preview` for complex reasoning, coding (1M tokens)
- Use `gemini-3-flash-preview` for fast, balanced performance (1M tokens)

> [!IMPORTANT]
> Models like `gemini-2.0-*`, `gemini-1.5-*` are legacy and deprecated.

🎓 设计原则总结

可复用的设计思想

描述驱动激活：通过精确的 description 匹配实现智能路由
渐进式加载：首层轻量匹配，按需加载详细内容
参考文档分离：主文件保持简洁，详细信息在 references/ 中按需获取
触发词映射：用户意图到文档的显式映射，避免模糊检索
跨平台兼容：一次编写，多端运行，降低维护成本

常见陷阱与避免

陷阱	避免方法
Description 过于宽泛	精确描述触发条件，避免所有请求都激活
参考文档过少	按场景充分拆分，每个文档聚焦单一主题
使用已废弃 API	在 Core Directives 中明确禁止，并提供迁移路径
版本信息过时	定期更新，或在 description 中注明版本依赖

🔗 相关资源

GitHub 仓库：google/skills
安装工具：skills.sh
官方文档：https://agentskills.io/home
安装命令：npx skills add google/skills

文档信息

难度：⭐⭐⭐⭐ | 类型：专家设计 | 更新日期：2026-04-25 | 预计阅读时间：25 分钟

更新于 2026-05-23

AI, Agent, Google Cloud, GKE, BigQuery, Gemini, 标准化

返回 | 主页

下一步

如果这篇内容对你有帮助，继续往更完整的路径里走。

你可以从专题页继续系统阅读，也可以通过联系页反馈想跟进的主题、工具和合作方向。

AI Agent 专题 Coding Agent 专题开源 AI 工具联系

目录

Google Agent Skills 全解析：AI Agent 的标准化技能框架

Google Agent Skills 全解析：AI Agent 的标准化技能框架

🎯 问题背景：AI Agent 的知识困境

AI Agent 开发的核心挑战

传统方案的局限

Google Agent Skills 的破局思路

📝 核心概念：SKILL.md 格式详解

技能文件结构

Frontmatter 字段说明

Description 的触发机制

核心指令区（Core Directives）

🔄 渐进式加载：避免上下文膨胀

核心设计思想

参考文档系统

触发词机制

🏗️ 架构设计：跨平台兼容

一次构建，多端运行

安装方式

与 MCP 的对比

📦 可用技能一览

Google Cloud 基础技能

配方技能（Recipes）

架构框架技能

💻 代码示例：Gemini API 实战

Python 快速开始

多语言 SDK 支持

认证配置

🗂️ 参考文档系统详解

GKE 技能参考文档映射

BigQuery 参考文档结构

🔧 高级特性

配方技能的工作流封装

版本迁移指导

模型推荐机制

🎓 设计原则总结

可复用的设计思想

常见陷阱与避免

🔗 相关资源

如果这篇内容对你有帮助，继续往更完整的路径里走。

与这篇内容相关的文章

AI副业早报 2026-05-22

AI新闻早报 2026-05-22

Chrome DevTools MCP：让 AI 编程代理操控 Chrome 的官方方案

Multica：用「时间共享」把 AI coding agent 从工具变成队友