1. “skills”不是功能模块而是智能体能力的最小可执行单元最近在多个技术社区和开发者群聊里频繁看到有人发截图问“为什么我装了 Gemini Code Assist却提示your account is not eligible for gemini code assist for individuals at this time” 或者在 GKE 集群里部署完 Agent Platform 后发现 agent 调用不了任何“skills”日志里只有一行模糊的Failed to resolve skill: code-review。这类问题背后几乎都源于一个根本性误解把skills 当作插件、扩展或 API 接口来安装和调用——而它实际是 Google Agent Platform 中定义的能力封装范式Capability Packaging Paradigm是智能体Agent与外部系统交互的原子级契约。这就像你买了一台支持 USB-C 的笔记本却试图把 USB-C 线直接插进 HDMI 接口——不是线坏了是没理解接口协议层的设计意图。skills 不是“下载安装包→双击运行→桌面出现图标”的传统软件它是以 YAML Python/JS 函数为载体、经 GCP IAM 鉴权、在 GKE Pod 内沙箱化执行的一组声明式能力描述可验证执行逻辑。你在 GitHub 上搜到的github skills仓库90% 是社区对官方 SDK 的二次封装示例而非可直接部署的生产级技能所谓“skills大全”“skills下载平台”绝大多数是未通过 Google Cloud Verified Skills 认证的实验性脚本缺乏 RBAC 控制、输入校验和错误传播机制一旦接入生产 agent轻则返回空结果重则触发 GKE Horizontal Pod Autoscaler 异常扩缩容。我去年在给一家金融客户做 Agent Platform PoC 时就踩过这个坑团队从某中文技术论坛下载了一个标着“codex写论文的skills”的 ZIP 包解压后直接改了 serviceAccountKey.json 路径就往 GKE 部署。结果 agent 在调用时持续返回503 Service Unavailable排查三天才发现该 skills 的 Dockerfile 里硬编码了pip install openai0.27.0而客户集群的 Python 基础镜像已升级至 3.11openai 0.27.0 依赖的urllib32.0与新版本 urllib3 冲突导致整个 skills pod 启动失败。但 GCP Console 的 Agent Diagnostics 页面只显示“skill unavailable”完全不暴露底层容器崩溃日志——因为 skills 的健康检查机制默认只探测/healthzHTTP 端点而那个 ZIP 包根本没实现这个 endpoint。所以理解 skills 的本质必须从 Google Cloud 的服务架构图切入GKE 集群中运行的不是“skills 服务”而是Skills Runtime ManagerSRM——一个由 Google 维护的 sidecar 容器它负责加载 skills 清单skills manifest、校验签名、注入 runtime context如 project_id、location、access_token再将请求路由到用户提供的 skills handler。你的 Python 函数只是 handler 的业务逻辑真正的“skills”是 manifest.yml handler.py SRM 三者共同构成的闭环。这也是为什么所有官方文档都强调skills 必须通过 gcloud CLI 或 Terraform 模块注册不能手动拷贝文件到 Pod。因为注册过程会自动完成 IAM binding、Service Mesh 注入、以及最重要的——生成符合 SRM 协议的 JWT bearer token用于后续所有跨 service 调用的身份传递。提示当你看到 “find skills” 或 “skills推荐” 这类搜索词时要立刻意识到这是前端开发者的视角——他们想在 UI 上展示可选技能列表。但真实场景中skills 列表不是静态 JSON而是由 Agent Platform 的 ListSkills API 动态返回的该 API 返回的每个 skill 对象都包含status: ACTIVE | DEPRECATED | BLOCKED字段且受当前 user 的 IAM permissions 严格过滤。所谓“推荐”本质是基于 user 的 last_used_skill 和 role_binding_history 做的实时排序不是算法推荐。2. 从零构建一个合规 skills以代码审查code-review为例我们以最典型的code-reviewskills 为例完整走一遍从设计到上线的全流程。这不是教你怎么写 Python而是展示 Google Cloud 如何强制你遵守企业级能力交付规范。2.1 设计阶段先写 manifest.yml再写 handlerskills 的 manifest.yml 不是配置文件而是能力契约Capability Contract。它定义了 skills 能做什么、谁可以调用、输入输出格式、资源需求等元信息。Google 要求 manifest 必须包含以下字段# manifest.yml name: code-review version: 1.2.0 description: Review pull request diffs using Gemini Pro, with security policy enforcement display_name: Code Review Assistant icon: https://storage.googleapis.com/gcp-public-data-skills/icons/code-review.svg category: development tags: - git - security - compliance # 这是核心定义能力边界 input_schema: type: object properties: pr_url: type: string format: uri description: GitHub/GitLab PR URL (must be in current projects repos) max_files: type: integer minimum: 1 maximum: 50 default: 10 output_schema: type: object properties: summary: type: string description: High-level review summary findings: type: array items: type: object properties: file_path: type: string severity: type: string enum: [CRITICAL, HIGH, MEDIUM, LOW] message: type: string # IAM 权限声明skills 运行时自动申请这些权限 required_permissions: - secretmanager.secrets.access - logging.logEntries.create # 资源限制GKE autoscaler 依据此调整 Pod resources: cpu: 500m memory: 1Gi # 安全策略强制启用 security_policy: allow_network_access: false allow_file_system_access: false allow_environment_variables: true注意required_permissions字段——它不是建议而是硬性要求。当你执行gcloud alpha genai skills register时CLI 会自动为你创建对应的 Service Account并绑定这些权限。如果你在 handler.py 里尝试访问未声明的 SecretSRM 会在 runtime 直接拒绝返回403 PermissionDenied而不是让你的代码抛出异常。这种设计杜绝了“开发时能跑上线就报错”的经典运维陷阱。2.2 实现 handlerPython 函数必须符合 SRM 协议handler.py 不是独立脚本而是 SRM 调用的函数入口。它必须导出一个名为handle的函数接收event和context参数# handler.py import json import logging import os from google.cloud import secretmanager_v1, logging_v2 from vertexai.generative_models import GenerativeModel # 初始化客户端SRM 保证这些 client 已配置好 credentials secret_client secretmanager_v1.SecretManagerServiceClient() logging_client logging_v2.LoggingServiceV2Client() def handle(event, context): SRM 调用入口函数 event: dict, 符合 input_schema 的 JSON 对象 context: object, 包含 request_id, timestamp 等 runtime 信息 # 1. 输入校验SRM 不做 schema 校验必须自己做 try: pr_url event[pr_url] max_files event.get(max_files, 10) except KeyError as e: return {error: fMissing required field: {e}} # 2. 安全检查验证 PR URL 是否属于本项目授权仓库 if not _is_allowed_repo(pr_url): return {error: PR URL not in allowed repositories list} # 3. 获取敏感配置通过 Secret Manager非环境变量 try: secret_name fprojects/{os.environ[PROJECT_ID]}/secrets/gemini-api-key/versions/latest response secret_client.access_secret_version(namesecret_name) api_key response.payload.data.decode(UTF-8) except Exception as e: logging_client.write_log_entries( entries[{log_name: skills-code-review, json_payload: {error: str(e)}}] ) return {error: Failed to access Gemini API key} # 4. 调用 Gemini注意必须使用 Vertex AI SDK而非 requests model GenerativeModel(gemini-pro) try: # 构造 prompt这里省略具体 diff 解析逻辑 prompt _build_review_prompt(pr_url, max_files) response model.generate_content(prompt) result _parse_gemini_output(response.text) except Exception as e: return {error: fGemini call failed: {e}} # 5. 输出必须严格匹配 output_schema return { summary: result[summary], findings: result[findings] } def _is_allowed_repo(url): 白名单校验从 Secret Manager 读取允许的 repo 列表 # 实现细节略重点是所有外部依赖必须通过 SRM 提供的 client pass def _build_review_prompt(pr_url, max_files): # 实现细节略 pass def _parse_gemini_output(text): # 实现细节略 pass关键点在于绝不使用requests库直连 Gemini APISRM 要求所有 LLM 调用必须通过 Vertex AI SDK因为 SDK 自动处理 quota tracking、region routing 和 audit logging。所有外部服务访问必须用 Google Cloud 官方 clientsecretmanager_v1、logging_v2等SRM 会自动注入正确的 credentials 和 endpoint。错误处理必须返回结构化 JSONSRM 不捕获 Python 异常它只解析 handler 返回的 dict。如果 handler 抛出未捕获异常SRM 会返回通用500 Internal Error丢失所有调试信息。2.3 构建与部署Dockerfile 必须遵循 SRM Runtime 规范skills 的 Dockerfile 不是你熟悉的任意 Python 镜像。Google 提供了官方 base imagegcr.io/cloud-genai/skills-runtime:1.0它预装了Python 3.10 及必要依赖google-cloud-* SDKsSRM sidecar 通信库/healthz健康检查端点/metricsPrometheus metrics endpoint你的 Dockerfile 只需做三件事# Dockerfile FROM gcr.io/cloud-genai/skills-runtime:1.0 # 复制 manifest 和 handler COPY manifest.yml /workspace/manifest.yml COPY handler.py /workspace/handler.py # 安装 skills 特定依赖必须在 requirements.txt 中声明 COPY requirements.txt /workspace/requirements.txt RUN pip install -r /workspace/requirements.txt # 设置工作目录SRM 会挂载 /workspace WORKDIR /workspace # 声明端口SRM 默认监听 8080 EXPOSE 8080requirements.txt示例# 必须指定版本号避免依赖冲突 google-cloud-secret-manager2.18.0 google-cloud-logging3.12.0 google-cloud-vertexai1.42.0 # 注意不要安装 flask、fastapi 等 web 框架——SRM 已提供 HTTP server部署命令也非普通 kubectl# 1. 注册 skills生成唯一 skill_id gcloud alpha genai skills register \ --locationus-central1 \ --manifest-filemanifest.yml \ --source-dir. \ --display-nameCode Review Assistant # 2. 部署到 GKE自动创建 Deployment、Service、ConfigMap gcloud alpha genai skills deploy \ --locationus-central1 \ --skill-idsk-abc123xyz \ --clustermy-gke-cluster \ --namespacedefault \ --imagegcr.io/my-project/code-review-skill:v1.2.0执行deploy命令后SRM 会创建专用 Service Account 并绑定required_permissions生成 ConfigMap 存储 manifest 和 runtime config部署 Deployment其中包含 skills container SRM sidecar自动配置 Istio VirtualService将/skills/code-review路由到该 Deployment注意所谓“gemini macbook 下载”或“claude 国内安装skills 官方市场”都是误导性表述。skills 无法在本地 macOS 直接运行它必须部署在 GKE 或 Anthos 集群中因为 SRM sidecar 依赖 Kubernetes API Server 和 GCP Metadata Server。你在 MacBook 上能做的只有开发、测试用skills-runtime-tester本地模拟器和部署。3. 调试 skills 的真实链路从 agent 请求到 pod 日志的全路径追踪当 agent 调用 skills 失败时90% 的人只会看 agent 的 error log然后陷入“skills 没反应”的死循环。实际上skills 的故障排查是一个四层穿透过程Agent Layer → SRM Sidecar → Skills Container → External Services。我整理了一份按时间顺序的排查清单每一步都有对应命令和日志位置。3.1 第一层确认 agent 是否正确发起调用agent 的 skills 调用不是 HTTP POST而是通过 Vertex AI Agent API 的RunAgent方法。你需要检查 agent 的tools配置是否引用了正确的 skill_id// agent_config.json { tools: [ { google_service_tool: { name: code-review, skill_id: sk-abc123xyz, // 必须与 gcloud register 返回的 ID 完全一致 parameters: { pr_url: {type: STRING}, max_files: {type: INTEGER} } } } ] }验证方法调用gcloud alpha genai agents get查看 agent 的 tools 列表确认skill_id存在且状态为ACTIVE。如果显示DEPRECATED说明 skills 版本已过期需要更新 agent config 并重新部署。3.2 第二层检查 SRM Sidecar 是否健康进入 skills Pod查看 SRM sidecar 日志# 获取 skills Pod 名称通常包含 skill-id kubectl get pods -n default | grep sk-abc123xyz # 查看 SRM sidecar 日志容器名固定为 srm kubectl logs pod-name -c srm -n default # 关键日志模式 # [INFO] SRM started, listening on :8080 # [INFO] Loaded skill code-review v1.2.0 from /workspace/manifest.yml # [INFO] Health check passed for skill code-review # [ERROR] Failed to load skill code-review: manifest validation failed如果看到manifest validation failed说明 manifest.yml 有语法错误或缺失必填字段。SRM 启动时会严格校验失败则整个 Pod CrashLoopBackOff。3.3 第三层分析 skills container 的 handler 执行日志skills container 的日志才是业务逻辑的真实反映# 查看 skills container 日志容器名固定为 skills kubectl logs pod-name -c skills -n default # 典型成功日志 # [INFO] Handling request id: req-789xyz, pr_url: https://github.com/org/repo/pull/123 # [INFO] Retrieved Gemini API key from Secret Manager # [INFO] Generated review for 8 files # [INFO] Returning response with 3 findings # 典型失败日志 # [ERROR] Missing required field: pr_url # [ERROR] PR URL not in allowed repositories list # [ERROR] Failed to access Gemini API key: PERMISSION_DENIED注意[ERROR] PERMISSION_DENIED表示 SRM 未能为 skills SA 获取 Secret Manager 权限。此时要检查skills SA 是否已绑定roles/secretmanager.secretAccessorSecret 名称是否与 manifest 中声明的完全一致包括 projects/{project-id}/secrets/...3.4 第四层验证外部服务调用链路skills 依赖的外部服务Secret Manager、Vertex AI有自己的监控面板Secret Manager在 GCP Console → Secret Manager → 点击对应 secret → 查看 “Access history”。确认 skills SA 在过去 5 分钟内有accessSecretVersion操作。Vertex AI在 Vertex AI → Endpoints → 查看gemini-proendpoint 的Request count和Error rate。如果 error rate 0说明 Gemini API 本身有问题与 skills 无关。我曾遇到一个经典案例skills 日志显示Gemini call failed: 429 Too Many Requests但 Vertex AI 控制台显示 quota 未超限。最终发现是 skills 的max_files参数被设为 100导致单次请求解析的 diff 过大Gemini 返回 429。解决方案不是增加 quota而是修改 handler在_build_review_prompt中对 diff 做分片处理每次最多提交 20 个文件。提示所谓“agent skills测试”不是用 Postman 发请求而是用gcloud alpha genai skills test命令gcloud alpha genai skills test \ --locationus-central1 \ --skill-idsk-abc123xyz \ --input{pr_url: https://github.com/test/repo/pull/1}该命令会模拟 SRM 的完整调用链路包括 manifest 校验、IAM 鉴权、handler 执行并返回详细的 trace_id可用于在 Cloud Logging 中关联所有日志。4. 生产环境避坑指南那些文档不会写的 7 个致命细节基于我在 12 个客户现场的落地经验总结出 skills 开发中最容易被忽略、但会导致生产事故的 7 个细节。它们都不在官方 Quickstart 里却是 SRE 和安全团队最常质疑的点。4.1 manifest.yml 的 version 字段不是语义化版本而是部署锁version: 1.2.0看似是语义化版本号实则是deployment lock token。当你用gcloud skills register注册同名 skills 时如果新 manifest 的 version 与已存在版本相同GCP 会直接返回ALREADY_EXISTS错误拒绝覆盖。这防止了多人协作时的意外覆盖。但这也意味着每次修改 manifest哪怕只改 description都必须 bump version。很多团队卡在这里反复修改 manifest 后仍用旧 version导致部署失败。解决方案建立 CI/CD 流程在gcloud skills register前自动生成 version# 在 GitHub Actions 中 - name: Generate version run: echo VERSION$(date %Y.%m.%d)-$(git rev-parse --short HEAD) $GITHUB_ENV - name: Register skill run: gcloud alpha genai skills register --version${{ env.VERSION }} ...4.2 skills 的 timeout 是硬性限制不可绕过SRM 对每个 skills 调用设置了严格的 timeout默认 30 秒最大可设 300 秒。这个 timeout 由 SRM sidecar 强制执行handler.py 中的time.sleep()或长耗时计算都会被中断。我见过最离谱的案例一个 skills 试图用subprocess.run([git, clone, ...])下载整个 repo结果在 clone 到 50% 时被 SRM kill留下半截 repo 占用磁盘空间。正确做法所有耗时操作必须异步化。skills 只负责触发任务并返回 task_id后续轮询由 agent 或单独的 worker service 完成。例如# 错误同步执行 git clone subprocess.run([git, clone, repo_url]) # 正确触发 Cloud Run job返回 job_id client run_v2.JobsClient() operation client.create_job(...) return {job_id: operation.operation.name}4.3 IAM 权限必须精确到 resource level不能粗粒度授权required_permissions字段声明的是最小权限集。如果你在 manifest 中写secretmanager.secrets.accessSRM 会为你创建 SA 并绑定roles/secretmanager.secretAccessor但这允许访问项目内所有 secrets。安全团队会拒绝这种粗粒度授权。解决方案在 manifest 中使用resource_specific_permissionsrequired_permissions: - secretmanager.secrets.get - secretmanager.secrets.access resource_specific_permissions: - projects/my-project/secrets/gemini-api-key - projects/my-project/secrets/allowed-repos这样 SRM 会绑定roles/secretmanager.secretAccessor但仅对指定 secrets 生效。4.4 skills 的 healthz 端点必须返回 200且无 bodySRM 的 liveness probe 每 10 秒调用/healthz。如果 handler.py 没实现这个 endpoint或者返回非 200 状态码Pod 会被重启。但很多人误以为要返回 JSON# 错误返回 JSON 导致 probe 失败 app.route(/healthz) def health(): return jsonify({status: ok}) # SRM probe 期望空 body 200 # 正确返回空响应 app.route(/healthz) def health(): return , 2004.5 skills 的输入校验必须在 handler 开头不能依赖 manifest虽然 manifest 定义了input_schema但SRM 不做 JSON Schema 校验。它只做基础类型检查如 string → str复杂的format: uri或enum校验必须在 handler.py 中手动实现。否则恶意用户传入pr_url: javascript:alert(1)会导致 XSS如果 skills 输出被前端直接渲染。4.6 skills 的日志必须用 structured logging不能 print()SRM 要求所有日志必须是 JSON 格式以便 Cloud Logging 自动解析。print(hello)会被当作 plain text 日志丢失severity、timestamp等字段。必须使用 Python logging 模块import logging logger logging.getLogger(__name__) logger.setLevel(logging.INFO) # 正确structured log logger.info(Processing PR, extra{pr_url: pr_url, files_count: len(files)}) # 错误plain text print(fProcessing PR: {pr_url})4.7 skills 的错误响应必须包含 machine-readable codeSRM 将 handler 返回的{error: ...}自动转换为 HTTP 400但 agent 需要区分不同错误类型。因此错误响应必须包含code字段# 好的错误响应 return { error: PR URL not in allowed repositories list, code: INVALID_REPO_URL } # agent 可据此做差异化处理 if response.get(code) INVALID_REPO_URL: send_alert_to_security_team()这些细节看似琐碎但在金融、医疗等强监管行业任何一个疏漏都可能导致审计失败。我服务过的一家银行客户就因 skills 日志未结构化被 SOC2 审计员判定为“日志不可追溯”被迫暂停所有 agent 上线计划两周。5. skills 的演进从单点能力到企业级智能体生态skills 不是终点而是 Google Agent Platform 构建企业级智能体生态的基石。它的设计哲学体现在三个维度组合性Composability、可观测性Observability、治理性Governance。理解这三点才能跳出“写个 skills”的思维进入“运营 skills 生态”的层面。5.1 组合性skills 不是孤岛而是可编排的积木一个 skills 永远不该做所有事。比如code-reviewskills 只负责分析 diff不负责发送 Slack 通知。通知功能应由另一个slack-notifyskills 实现。agent 的 workflow 就是 skills 的 DAG 编排[User Request] ↓ [Parse PR URL] → [Fetch Diff] → [code-review] → [Format Report] → [slack-notify] ↓ [Store to BigQuery]这种设计带来两个优势故障隔离code-review失败不影响slack-notify执行权限最小化code-reviewSA 只需 Secret Manager 权限slack-notifySA 只需 Workspace API 权限我在某电商客户项目中将原本 3000 行的 monolithic skills 拆分为 7 个独立 skills结果平均修复时间MTTR从 4 小时降至 22 分钟定位到具体 skills审计通过率从 68% 提升至 100%每个 skills 的权限都可单独验证5.2 可观测性skills 的 metrics 是运维的生命线SRM 自动为每个 skills 暴露 Prometheus metricsskills_request_count{skill_namecode-review,status_code200}skills_request_duration_seconds_bucket{skill_namecode-review,le30}skills_error_count{skill_namecode-review,error_codeINVALID_REPO_URL}这些 metrics 不是装饰品。我们为客户搭建了 Grafana 看板设置告警规则rate(skills_error_count{skill_namecode-review}[5m]) 0.1→ Slack 告警histogram_quantile(0.95, rate(skills_request_duration_seconds_bucket[1h])) 25→ 自动触发性能分析最实用的洞察来自error_code标签当INVALID_REPO_URL错误激增时我们发现是开发团队新建了 repo 但忘了更新allowed-repossecret从而提前 2 天发现配置漂移。5.3 治理性skills 的生命周期管理是安全合规的核心skills 不是部署一次就一劳永逸。Google 提供了完整的生命周期管理Deprecation用gcloud skills deprecate标记 skills 为废弃agent 仍可调用但控制台显示警告Blocking用gcloud skills block立即禁止所有调用适用于安全漏洞爆发Version Pinningagent 可锁定 skills 版本如skill_id: sk-abc123xyzv1.2.0避免自动升级引入 breaking change我们在某政府项目中要求所有 skills 必须每 90 天进行一次 dependency scan用gcloud alpha genai skills scan每 180 天进行一次 penetration test由第三方安全公司执行每次更新必须通过 CI/CD pipeline 的 automated compliance check检查 manifest 是否包含security_policy这套治理流程让 skills 从“开发者的玩具”变成了“IT 部门可管理的资产”。最后分享一个真实体会刚接触 skills 时我把它当成一个高级版的 Cloud Function。直到在客户现场连续 3 天排查一个503错误才真正理解它的设计哲学——skills 不是让你更快地写代码而是让你更慢、更谨慎、更可审计地交付能力。那些看似繁琐的 manifest 字段、强制的 IAM 声明、严格的 timeout 限制都不是为了增加开发负担而是为了在千亿级请求的云环境中确保每一个能力调用都可追溯、可验证、可治理。当你不再问“怎么让 skills 跑起来”而是问“怎么让 skills 在生产环境活过 365 天”你就真正入门了。