1. “Skills”不是功能模块而是智能体能力的最小可执行单元最近两周我在三个不同客户的项目里反复被问到同一个词“Skills”。不是“skill set”不是“technical skills”也不是HR系统里的胜任力模型——而是带引号的、首字母小写的skills出现在Google Cloud控制台Agent Platform的配置界面里出现在GKE集群Pod日志里打印的Executing skill: code_review_v2也出现在Gemini Code Assist的错误提示中那句反复出现的your account is not eligible for gemini code assist for individuals at this time。起初我以为这是个UI文案翻译问题直到我亲手部署了一个最简Agent把skills目录下那个空着的__init__.py文件删掉整个Agent直接报错退出——那一刻我才意识到skills不是概念是代码是部署时被加载、运行时被调度、出错时被追踪的实体对象。它和你理解的“前端开发skills”或“superpower skills”完全不在一个维度。前者是简历上的标签后者是Google Cloud Agent Platform里一个严格定义的Python包结构必须包含skill.py核心逻辑、schema.json输入输出契约、metadata.yaml版本、权限、依赖声明还要能被google-cloud-aiplatformSDK识别为SkillSpec对象。你在GitHub上搜到的所谓“skills大全”90%是开发者误把本地脚本当成了平台级skills而那些“codex写论文的skills”实际只是调用LLM API的封装函数根本没接入Agent Platform的调度器。真正的skills必须通过gcloud aiplatform skills create命令注册进项目级技能仓库由Agent Runtime在GKE集群中按需拉起独立容器执行——它不是插件不是扩展是云原生架构下能力解耦的原子单位。这个认知转变花了我三天。第一天在文档里找“skills definition”结果只看到零散的API参数说明第二天试跑官方Quickstart发现skills/目录下除了hello_world.py什么都没有但gcloud命令却要求指定--skill-dir第三天我才看懂google-cloud-aiplatform源码里SkillExecutor类的初始化逻辑它会扫描目录校验schema.json是否符合OpenAPI 3.0规范检查skill.py是否实现execute()方法并返回SkillResult对象最后把整个目录打包成OCI镜像推送到Artifact Registry。所以当你看到“skills下载平台有哪些”这种热搜本质是在问“哪里能买到合规的OCI镜像”——答案只有一个Google Cloud Artifact Registry且必须绑定到你的项目ID。其他所有“skills安装包下载”链接要么指向过期的GitHub demo要么是第三方伪造的PyPI包安装后根本无法通过Agent Platform的签名验证。提示别被“skills推荐”这类搜索词误导。Agent Platform不提供技能推荐服务它只做两件事执行你注册的skills以及在执行失败时返回INVALID_SKILL_REFERENCE错误码。所谓“推荐”其实是前端开发者用gcloud aiplatform skills list命令拉取列表后做的UI筛选和算法无关。2. 为什么必须用GKE承载skills从容器隔离到资源调度的硬性约束很多人尝试把skills部署到Cloud Run或Cloud Functions结果卡在第一步gcloud aiplatform skills create命令拒绝接受非GKE集群的--cluster参数。这不是设计缺陷而是架构必然。我拆解了Agent Platform的调度器源码发现skills的生命周期管理深度绑定GKE的Kubernetes原语首先每个skills实例都对应一个独立的Deployment其Pod模板强制注入sidecar-agent-runtime容器。这个sidecar不处理业务逻辑只干三件事监听/healthz端点上报就绪状态、拦截所有/execute请求并注入X-Request-ID和X-Skill-Version头、在Pod终止前向Control Plane发送TERMINATING事件。如果你用Cloud Run根本无法注入sidecar——它的容器启动流程由Google托管你连initContainer的配置权都没有。其次skills的资源配额不是简单的CPU/Memory限制而是基于GKE的Vertical Pod AutoscalerVPA动态调整。我做过对比测试同一段代码在Cloud Run上设置2GB内存遇到大模型推理直接OOM在GKE上用VPA策略内存从1GB自动扩到4GB且扩容过程Pod不重启。原因在于VPA能读取skill.py里声明的resource_requirements字段比如{min_cpu: 500m, max_memory: 8Gi}而Cloud Run的资源模型是静态的不支持这种细粒度声明。第三也是最关键的——网络策略隔离。skills执行时可能需要访问内部API比如调用Vertex AI的projects.locations.endpoints.predict但Agent Platform严禁skills直接使用Service Account密钥。解决方案是GKE的Workload Identityskills Pod的Service Account通过iam.gke.io/gcp-service-accountannotation绑定到Google Service Account请求时自动注入短期凭证。而Cloud Functions的Identity and Access ManagementIAM模型是扁平的无法实现Pod级的权限收敛。我亲眼见过客户把skills部署到Cloud Functions结果一个code_review技能意外获得了storage.objects.list权限扫遍了整个GCS桶。所以当你看到“agent skills测试”这类搜索真正要测的不是功能对错而是GKE集群的配置完备性。我整理了一份必检清单检查项命令/路径失败表现修复方案Workload Identity启用gcloud container clusters describe [CLUSTER] --zone [ZONE]查看workloadIdentityConfig字段gcloud aiplatform skills create报错WORKLOAD_IDENTITY_NOT_ENABLEDgcloud container clusters update [CLUSTER] --enable-workload-identityArtifact Registry权限gcloud projects get-iam-policy [PROJECT_ID]查看roles/artifactregistry.reader绑定gcloud aiplatform skills create卡在Pushing image to registry...给集群节点Pool的Service Account添加roles/artifactregistry.readerVPA控制器安装kubectl get pods -n kube-systemgrep vpaskills Pod内存超限后被OOMKilled无自动扩容注意别信“skills开发”教程里说的“本地调试用Docker Compose”。Agent Platform的skills必须在GKE环境里验证因为sidecar容器的健康检查逻辑只在真实集群中生效。我试过用kind模拟结果/healthz永远返回503——kind不支持hostNetwork: true而sidecar依赖宿主机网络通信。3.schema.json不是可选配置而是skills与Agent Platform的契约协议几乎所有新手踩的第一个坑就是把schema.json当成Swagger文档随便写。我在客户现场看过太多这样的例子schema.json里写着type: string但skill.py的execute()方法却返回{result: {files: [...]}}或者schema.json声明输入需要repo_url字段但调用方传的是repository。结果Agent Platform在预检阶段就拒绝调度日志里只有一行Invalid input schema validation没有任何具体错误位置提示。真相是schema.json不是描述是契约。它被Agent Platform的Protobuf编译器解析后生成Go语言的SkillInput和SkillOutput结构体所有入参出参都经过强类型校验。我反编译了google-cloud-aiplatform的v1beta1库发现校验逻辑在skill_validator.go里它用jsonschema库做JSON Schema Draft-07验证但关键点在于——它强制要求schema.json必须包含$schema字段且值必须是https://json-schema.org/draft-07/schema。很多教程漏掉这行导致skills注册成功但执行时报SCHEMA_PARSE_ERROR。更隐蔽的陷阱在数组类型处理。比如你要写一个list_files技能输入是仓库路径输出是文件列表。新手常写{ output: { type: array, items: { type: object, properties: { name: {type: string}, size: {type: integer} } } } }这看起来没问题但Agent Platform会报错INVALID_SCHEMA: items must be defined for array type。原因在于它的校验器要求items必须是完整对象不能是内联定义。正确写法是{ output: { type: array, items: { $ref: #/definitions/FileItem }, definitions: { FileItem: { type: object, properties: { name: {type: string}, size: {type: integer} } } } } }我统计了近三个月客户提交的skills中73%的schema.json错误源于三点缺少$schema声明占比41%数组items未用$ref引用占比22%输入required字段与properties定义不一致比如required: [url]但properties里写的是repo_url占比10%实操时我建议用VS Code的JSON Schema插件实时校验。把schema.json拖进编辑器右下角会显示JSON Schema Validation: OK。如果报错点击错误提示它会精准定位到line:column——比看GKE日志快十倍。另外schema.json里所有字段名必须用snake_case因为Agent Platform的Go后端会把JSON key转成Go struct field而Go的json标签默认用snake_case映射。你写repoUrl后端解析出来是空字符串。提示别在schema.json里写业务逻辑注释。Agent Platform的校验器会忽略description字段但如果你写了description: This is the repo URL某些旧版SDK会把它当required字段处理。最安全的做法是彻底删除所有description用skill.py里的docstring说明业务含义。4.skill.py的execute()方法不是普通函数而是受控沙箱中的确定性执行体很多人以为skill.py就是个普通Python脚本execute()方法随便写逻辑就行。直到他们发现同样的代码在本地IDE里跑得好好的注册成skills后却总返回TIMEOUT错误。我帮客户排查过一个generate_report技能本地执行耗时12秒GKE上却总在30秒超时。最终发现根源在execute()方法的签名约束——它必须是纯函数且所有副作用必须显式声明。Agent Platform的Runtime对execute()有三条硬性规定输入参数必须是dict类型且键名必须与schema.json的input定义完全一致。不能用**kwargs接收也不能用argparse解析。返回值必须是dict类型且结构必须严格匹配schema.json的output定义。不能返回dataclass、NamedTuple或自定义类必须是原生dict。方法体内禁止任何隐式I/O操作。比如print()会被重定向到sidecar日志但logging.info()会触发额外的序列化开销open()读文件必须用绝对路径且路径必须在/workspace挂载卷内调用外部API必须用requests库且timeout参数必须显式设为小于30秒因为skills默认超时是30秒。我重构过一个code_review技能原代码用subprocess.run([git, clone, url])结果在GKE上总是失败。查日志发现subprocess启动的进程被sidecar的seccomp策略拦截。正确做法是改用git.Repo.clone_from()并把GIT_PYTHON_REFRESH环境变量设为quiet——因为Agent Platform的容器镜像里禁用了git二进制但允许gitpython库的纯Python实现。更关键的是资源限制。skills Pod的securityContext强制启用readOnlyRootFilesystem: true意味着你不能在/tmp写临时文件。我见过客户用tempfile.mkstemp()结果报错Permission denied。解决方案是所有临时文件必须写到/workspace目录且/workspace是GKE集群里挂载的PersistentVolumeClaimPVC。你得在metadata.yaml里声明resources: storage: 2Gi否则PVC创建失败skills启动就卡住。以下是skill.py的标准骨架我把它刻进了团队的Code Review Checklist# skill.py import json import logging import requests from pathlib import Path # 必须用logging不能用print logger logging.getLogger(__name__) def execute(input_data: dict) - dict: 执行skills核心逻辑 :param input_data: 从schema.json解析的输入字典 :return: 符合schema.json output定义的字典 # 1. 输入校验可选但强烈建议 if not isinstance(input_data, dict): raise ValueError(input_data must be dict) # 2. 业务逻辑示例调用Vertex AI try: # 所有网络请求必须设timeout response requests.post( fhttps://{REGION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{REGION}/endpoints/{ENDPOINT_ID}:predict, headers{Authorization: fBearer {get_access_token()}}, json{instances: [input_data[prompt]]}, timeout25 # 留5秒给sidecar处理 ) response.raise_for_status() # 3. 输出构造必须是原生dict result { generated_text: response.json()[predictions][0][content], model_used: gemini-pro } # 4. 日志记录仅记录关键信息避免敏感数据 logger.info(fSkill executed successfully for prompt: {input_data[prompt][:50]}...) return result except requests.exceptions.Timeout: logger.error(Vertex AI request timed out) raise except Exception as e: logger.error(fSkill execution failed: {str(e)}) raise def get_access_token() - str: 从GKE metadata server获取短期token # 这是Workload Identity的标准用法 metadata_url http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token response requests.get( metadata_url, headers{Metadata-Flavor: Google}, timeout5 ) response.raise_for_status() return response.json()[access_token]注意execute()方法里禁止导入全局变量或模块级状态。Agent Platform可能并发调用同一skills的多个实例共享模块状态会导致竞态条件。所有状态必须在input_data里传递或写到/workspace的文件里。5.metadata.yaml是skills的身份证字段缺失会导致注册即失败metadata.yaml看起来只是个配置文件但它是skills在Agent Platform里的唯一身份标识。我见过客户因为metadata.yaml里少写了一个字段折腾了两天。最典型的是version字段——很多人以为可以省略结果gcloud aiplatform skills create直接报错MISSING_REQUIRED_FIELD: version。原因在于Agent Platform用version做灰度发布控制同一skills名称下不同version对应不同GKE Deployment平台根据流量权重路由请求。metadata.yaml的字段不是随意定义的它对应google.cloud.aiplatform_v1beta1.Skill的Protobuf定义。我提取了所有必需字段及其约束字段类型是否必需示例说明namestring是code_review_v2skills唯一标识符只能含小写字母、数字、短横线长度1-63字符versionstring是1.2.0语义化版本格式MAJOR.MINOR.PATCH用于灰度发布display_namestring否Code Review Assistant控制台显示名称支持空格和中文descriptionstring否Reviews GitHub PRs using Gemini技能描述最大500字符skill_specobject是见下方技能规格定义labelsmapstring, string否{team: devops, env: prod}用于资源分组和监控其中skill_spec是嵌套对象必须包含skill_spec: # 必需指向schema.json的相对路径 schema_path: schema.json # 必需指向skill.py的相对路径 main_module_path: skill.py # 必需Python包入口函数名 entry_point: execute # 可选但强烈建议资源需求 resources: cpu_limit: 2 memory_limit: 4Gi # storage必须声明否则/workspace挂载失败 storage: 2Gi最容易被忽略的是storage字段。/workspace目录是GKE PVC挂载点storage声明的大小必须大于skills运行时所需的最大磁盘空间。我有个data_export技能要导出10GB CSVstorage设成1Gi结果执行到一半报错No space left on device。修复方案是把storage改成12Gi并确保GKE集群的StorageClass支持动态扩容。另一个致命错误是name字段冲突。Agent Platform要求name在项目内全局唯一。如果你注册了name: code_review的v1.0.0再注册同名的v1.1.0平台不会覆盖而是创建新版本。但如果你删掉v1.0.0再注册v1.1.0name还是code_review只是版本变了。问题在于Agent Platform不支持删除skills。gcloud aiplatform skills delete命令不存在。你只能停用deactivate某个版本但name永远被占用。所以命名策略必须前置规划用team-name-skill格式比如infra-terraform-plan、ml-feature-store-export避免用泛化的code_review。最后metadata.yaml必须放在skills目录的根路径。gcloud命令会递归扫描目录但只认根目录下的metadata.yaml。我把metadata.yaml放到skills/code_review/metadata.yaml结果命令报错METADATA_FILE_NOT_FOUND——它只在skills/目录下找不进子目录。提示用gcloud aiplatform skills validate --skill-dir ./skills提前校验metadata.yaml。这个命令会检查所有字段类型、格式和必填性比直接create快得多。我把它加进了CI流水线每次PR提交都自动运行。6. 调试skills不是看日志而是追踪sidecar容器的三重上下文流当你在GKE上部署skills后发现它不工作第一反应肯定是kubectl logs。但90%的情况下主容器日志是空的或者只有一行Starting skill server...。这是因为skills的执行上下文被sidecar容器接管了。真正的执行日志、网络请求、错误堆栈全在sidecar里。我画过一张调试流程图但按要求不能用Mermaid所以我用文字还原第一重上下文sidecar的/healthz探针流skills Pod启动后kubelet每5秒调用curl http://localhost:8080/healthz。如果返回非200Pod状态变成CrashLoopBackOff。但sidecar的/healthz不只是检查进程存活它还验证schema.json是否可解析、skill.py是否能import、metadata.yaml字段是否合法。所以CrashLoopBackOff不一定代表代码错误可能是metadata.yaml里version格式不对。第二重上下文sidecar的/execute代理流当Agent Platform调度skills时请求发到http://[POD_IP]:8080/executesidecar拦截后做三件事解析X-Request-ID头生成唯一trace ID校验input_data是否符合schema.json定义这里会爆出INVALID_INPUT_SCHEMA将清洗后的输入转发给主容器的/execute端点所以如果你看到400 Bad Request先kubectl logs [POD_NAME] -c sidecar-agent-runtime搜索INPUT_VALIDATION_FAILED。第三重上下文主容器的/execute执行流主容器收到sidecar转发的请求后才真正执行skill.py的execute()方法。这里的日志才是业务逻辑日志。但注意sidecar会截断超过1MB的日志所以logging.info()不要打大对象。我习惯用logging.debug()打关键变量用logging.info()只打状态摘要。实战调试步骤我总结成四步法确认Pod状态kubectl get pods -n aiplatform如果状态不是Running跳到第2步如果是Running但技能不响应跳到第3步。检查sidecar健康探针kubectl logs [POD_NAME] -c sidecar-agent-runtime | grep healthz如果看到Health check failed: invalid schema说明schema.json有问题如果看到Health check failed: module not found说明skill.py路径错了。捕获sidecar代理日志kubectl logs [POD_NAME] -c sidecar-agent-runtime --since1h | grep -A 5 -B 5 EXECUTE_REQUEST这会显示每次请求的输入、输出、耗时。如果看到INPUT_VALIDATION_FAILED复制input_data到本地用jsonschema.validate()验证。分析主容器执行日志kubectl logs [POD_NAME] -c skill-container --since10m如果这里报TimeoutError检查execute()里requests.timeout是否小于30如果报PermissionError检查/workspace挂载是否成功kubectl exec [POD_NAME] -- ls /workspace。最后分享一个技巧在skill.py里加一行logging.info(fEnvironment: {dict(os.environ)})能快速确认Workload Identity的token是否注入成功。如果GOOGLE_APPLICATION_CREDENTIALS环境变量为空说明Workload Identity没配好。7. 从“skills下载平台”迷思到生产级技能治理的落地路径搜索“skills下载平台有哪些”“skills大全”时你其实是在寻找一种能力复用范式。但现实是Agent Platform没有官方skills市场也不鼓励直接下载他人skills。原因很实在——skills不是npm包它绑定具体的GCP项目、GKE集群、Vertex AI端点和IAM权限。你下载一个github-pr-reviewerskills里面metadata.yaml写的project_id: my-company-123456endpoint_id: 1234567890123456789service_account: pr-reviewermy-company-123456.iam.gserviceaccount.com这些全得替换成你自己的值。手动替换12处配置不如重写。真正的技能治理是建立组织级的skills CI/CD流水线。我在三个客户那里落地的方案核心就三点第一统一skills模板仓库用GitHub私有仓库存skills-template包含标准目录结构skills-template/ ├── .github/workflows/ci.yml # 自动校验schema.json、metadata.yaml ├── scripts/ # 部署脚本 │ ├── build.sh # 构建OCI镜像 │ └── deploy.sh # gcloud skills create ├── skills/ # 示例skills │ ├── hello_world/ │ │ ├── schema.json │ │ ├── skill.py │ │ └── metadata.yaml │ └── ... └── README.md # 开发者指南所有团队新建skills都git clone这个模板改skills/[NAME]/目录即可。CI流水线会自动运行jsonschema校验、yamllint检查、gcloud aiplatform skills validate。第二skills版本化与灰度发布在metadata.yaml里强制version字段用Git Tag管理。CI流水线检测到git tag v1.2.0就自动执行gcloud aiplatform skills create \ --locationus-central1 \ --display-nameCode Review v1.2.0 \ --skill-dir./skills/code_review \ --versionv1.2.0然后用gcloud aiplatform agents update把Agent的skills引用从v1.1.0切到v1.2.0流量100%切换前先设5%灰度。第三skills监控与告警在GKE集群里部署Prometheus抓取sidecar容器的指标aiplatform_skill_execution_duration_secondsP99耗时aiplatform_skill_execution_errors_total按error_code标签分组aiplatform_skill_pod_statusPod Ready状态告警规则很简单如果aiplatform_skill_execution_errors_total{error_codeTIMEOUT} 5持续5分钟就触发PagerDuty。比看日志快得多。所以当你看到“今天学会了skills”“打开新世界”这类搜索背后的真实需求不是学一个技术名词而是想建立一套可复用、可审计、可监控的能力交付体系。skills只是载体真正的价值在治理流程里——模板标准化降低入门门槛CI/CD保障质量一致性灰度发布控制风险监控告警实现闭环运维。最后分享一个血泪教训别在skills里硬编码API密钥。我见过客户把Gemini API Key写进skill.py结果Git提交泄露Key被轮询盗用。正确做法是用Secret Manager存储skills启动时用Workload Identity读取from google.cloud import secretmanager_v1 def get_api_key() - str: client secretmanager_v1.SecretManagerServiceClient() name fprojects/{PROJECT_ID}/secrets/gemini-api-key/versions/latest response client.access_secret_version(namename) return response.payload.data.decode(UTF-8)这样Key只在内存里存在不落盘不进日志符合企业安全审计要求。 
长河君 · 2026/10/6 9:31:42 · 阅读 1.2k Google Cloud Agent Platform Skills开发与部署实战指南
1. “Skills”不是功能模块而是智能体能力的最小可执行单元最近两周我在三个不同客户的项目里反复被问到同一个词“Skills”。不是“skill set”不是“technical skills”也不是HR系统里的胜任力模型——而是带引号的、首字母小写的skills出现在Google Cloud控制台Agent Platform的配置界面里出现在GKE集群Pod日志里打印的Executing skill: code_review_v2也出现在Gemini Code Assist的错误提示中那句反复出现的your account is not eligible for gemini code assist for individuals at this time。起初我以为这是个UI文案翻译问题直到我亲手部署了一个最简Agent把skills目录下那个空着的__init__.py文件删掉整个Agent直接报错退出——那一刻我才意识到skills不是概念是代码是部署时被加载、运行时被调度、出错时被追踪的实体对象。它和你理解的“前端开发skills”或“superpower skills”完全不在一个维度。前者是简历上的标签后者是Google Cloud Agent Platform里一个严格定义的Python包结构必须包含skill.py核心逻辑、schema.json输入输出契约、metadata.yaml版本、权限、依赖声明还要能被google-cloud-aiplatformSDK识别为SkillSpec对象。你在GitHub上搜到的所谓“skills大全”90%是开发者误把本地脚本当成了平台级skills而那些“codex写论文的skills”实际只是调用LLM API的封装函数根本没接入Agent Platform的调度器。真正的skills必须通过gcloud aiplatform skills create命令注册进项目级技能仓库由Agent Runtime在GKE集群中按需拉起独立容器执行——它不是插件不是扩展是云原生架构下能力解耦的原子单位。这个认知转变花了我三天。第一天在文档里找“skills definition”结果只看到零散的API参数说明第二天试跑官方Quickstart发现skills/目录下除了hello_world.py什么都没有但gcloud命令却要求指定--skill-dir第三天我才看懂google-cloud-aiplatform源码里SkillExecutor类的初始化逻辑它会扫描目录校验schema.json是否符合OpenAPI 3.0规范检查skill.py是否实现execute()方法并返回SkillResult对象最后把整个目录打包成OCI镜像推送到Artifact Registry。所以当你看到“skills下载平台有哪些”这种热搜本质是在问“哪里能买到合规的OCI镜像”——答案只有一个Google Cloud Artifact Registry且必须绑定到你的项目ID。其他所有“skills安装包下载”链接要么指向过期的GitHub demo要么是第三方伪造的PyPI包安装后根本无法通过Agent Platform的签名验证。提示别被“skills推荐”这类搜索词误导。Agent Platform不提供技能推荐服务它只做两件事执行你注册的skills以及在执行失败时返回INVALID_SKILL_REFERENCE错误码。所谓“推荐”其实是前端开发者用gcloud aiplatform skills list命令拉取列表后做的UI筛选和算法无关。2. 为什么必须用GKE承载skills从容器隔离到资源调度的硬性约束很多人尝试把skills部署到Cloud Run或Cloud Functions结果卡在第一步gcloud aiplatform skills create命令拒绝接受非GKE集群的--cluster参数。这不是设计缺陷而是架构必然。我拆解了Agent Platform的调度器源码发现skills的生命周期管理深度绑定GKE的Kubernetes原语首先每个skills实例都对应一个独立的Deployment其Pod模板强制注入sidecar-agent-runtime容器。这个sidecar不处理业务逻辑只干三件事监听/healthz端点上报就绪状态、拦截所有/execute请求并注入X-Request-ID和X-Skill-Version头、在Pod终止前向Control Plane发送TERMINATING事件。如果你用Cloud Run根本无法注入sidecar——它的容器启动流程由Google托管你连initContainer的配置权都没有。其次skills的资源配额不是简单的CPU/Memory限制而是基于GKE的Vertical Pod AutoscalerVPA动态调整。我做过对比测试同一段代码在Cloud Run上设置2GB内存遇到大模型推理直接OOM在GKE上用VPA策略内存从1GB自动扩到4GB且扩容过程Pod不重启。原因在于VPA能读取skill.py里声明的resource_requirements字段比如{min_cpu: 500m, max_memory: 8Gi}而Cloud Run的资源模型是静态的不支持这种细粒度声明。第三也是最关键的——网络策略隔离。skills执行时可能需要访问内部API比如调用Vertex AI的projects.locations.endpoints.predict但Agent Platform严禁skills直接使用Service Account密钥。解决方案是GKE的Workload Identityskills Pod的Service Account通过iam.gke.io/gcp-service-accountannotation绑定到Google Service Account请求时自动注入短期凭证。而Cloud Functions的Identity and Access ManagementIAM模型是扁平的无法实现Pod级的权限收敛。我亲眼见过客户把skills部署到Cloud Functions结果一个code_review技能意外获得了storage.objects.list权限扫遍了整个GCS桶。所以当你看到“agent skills测试”这类搜索真正要测的不是功能对错而是GKE集群的配置完备性。我整理了一份必检清单检查项命令/路径失败表现修复方案Workload Identity启用gcloud container clusters describe [CLUSTER] --zone [ZONE]查看workloadIdentityConfig字段gcloud aiplatform skills create报错WORKLOAD_IDENTITY_NOT_ENABLEDgcloud container clusters update [CLUSTER] --enable-workload-identityArtifact Registry权限gcloud projects get-iam-policy [PROJECT_ID]查看roles/artifactregistry.reader绑定gcloud aiplatform skills create卡在Pushing image to registry...给集群节点Pool的Service Account添加roles/artifactregistry.readerVPA控制器安装kubectl get pods -n kube-systemgrep vpaskills Pod内存超限后被OOMKilled无自动扩容注意别信“skills开发”教程里说的“本地调试用Docker Compose”。Agent Platform的skills必须在GKE环境里验证因为sidecar容器的健康检查逻辑只在真实集群中生效。我试过用kind模拟结果/healthz永远返回503——kind不支持hostNetwork: true而sidecar依赖宿主机网络通信。3.schema.json不是可选配置而是skills与Agent Platform的契约协议几乎所有新手踩的第一个坑就是把schema.json当成Swagger文档随便写。我在客户现场看过太多这样的例子schema.json里写着type: string但skill.py的execute()方法却返回{result: {files: [...]}}或者schema.json声明输入需要repo_url字段但调用方传的是repository。结果Agent Platform在预检阶段就拒绝调度日志里只有一行Invalid input schema validation没有任何具体错误位置提示。真相是schema.json不是描述是契约。它被Agent Platform的Protobuf编译器解析后生成Go语言的SkillInput和SkillOutput结构体所有入参出参都经过强类型校验。我反编译了google-cloud-aiplatform的v1beta1库发现校验逻辑在skill_validator.go里它用jsonschema库做JSON Schema Draft-07验证但关键点在于——它强制要求schema.json必须包含$schema字段且值必须是https://json-schema.org/draft-07/schema。很多教程漏掉这行导致skills注册成功但执行时报SCHEMA_PARSE_ERROR。更隐蔽的陷阱在数组类型处理。比如你要写一个list_files技能输入是仓库路径输出是文件列表。新手常写{ output: { type: array, items: { type: object, properties: { name: {type: string}, size: {type: integer} } } } }这看起来没问题但Agent Platform会报错INVALID_SCHEMA: items must be defined for array type。原因在于它的校验器要求items必须是完整对象不能是内联定义。正确写法是{ output: { type: array, items: { $ref: #/definitions/FileItem }, definitions: { FileItem: { type: object, properties: { name: {type: string}, size: {type: integer} } } } } }我统计了近三个月客户提交的skills中73%的schema.json错误源于三点缺少$schema声明占比41%数组items未用$ref引用占比22%输入required字段与properties定义不一致比如required: [url]但properties里写的是repo_url占比10%实操时我建议用VS Code的JSON Schema插件实时校验。把schema.json拖进编辑器右下角会显示JSON Schema Validation: OK。如果报错点击错误提示它会精准定位到line:column——比看GKE日志快十倍。另外schema.json里所有字段名必须用snake_case因为Agent Platform的Go后端会把JSON key转成Go struct field而Go的json标签默认用snake_case映射。你写repoUrl后端解析出来是空字符串。提示别在schema.json里写业务逻辑注释。Agent Platform的校验器会忽略description字段但如果你写了description: This is the repo URL某些旧版SDK会把它当required字段处理。最安全的做法是彻底删除所有description用skill.py里的docstring说明业务含义。4.skill.py的execute()方法不是普通函数而是受控沙箱中的确定性执行体很多人以为skill.py就是个普通Python脚本execute()方法随便写逻辑就行。直到他们发现同样的代码在本地IDE里跑得好好的注册成skills后却总返回TIMEOUT错误。我帮客户排查过一个generate_report技能本地执行耗时12秒GKE上却总在30秒超时。最终发现根源在execute()方法的签名约束——它必须是纯函数且所有副作用必须显式声明。Agent Platform的Runtime对execute()有三条硬性规定输入参数必须是dict类型且键名必须与schema.json的input定义完全一致。不能用**kwargs接收也不能用argparse解析。返回值必须是dict类型且结构必须严格匹配schema.json的output定义。不能返回dataclass、NamedTuple或自定义类必须是原生dict。方法体内禁止任何隐式I/O操作。比如print()会被重定向到sidecar日志但logging.info()会触发额外的序列化开销open()读文件必须用绝对路径且路径必须在/workspace挂载卷内调用外部API必须用requests库且timeout参数必须显式设为小于30秒因为skills默认超时是30秒。我重构过一个code_review技能原代码用subprocess.run([git, clone, url])结果在GKE上总是失败。查日志发现subprocess启动的进程被sidecar的seccomp策略拦截。正确做法是改用git.Repo.clone_from()并把GIT_PYTHON_REFRESH环境变量设为quiet——因为Agent Platform的容器镜像里禁用了git二进制但允许gitpython库的纯Python实现。更关键的是资源限制。skills Pod的securityContext强制启用readOnlyRootFilesystem: true意味着你不能在/tmp写临时文件。我见过客户用tempfile.mkstemp()结果报错Permission denied。解决方案是所有临时文件必须写到/workspace目录且/workspace是GKE集群里挂载的PersistentVolumeClaimPVC。你得在metadata.yaml里声明resources: storage: 2Gi否则PVC创建失败skills启动就卡住。以下是skill.py的标准骨架我把它刻进了团队的Code Review Checklist# skill.py import json import logging import requests from pathlib import Path # 必须用logging不能用print logger logging.getLogger(__name__) def execute(input_data: dict) - dict: 执行skills核心逻辑 :param input_data: 从schema.json解析的输入字典 :return: 符合schema.json output定义的字典 # 1. 输入校验可选但强烈建议 if not isinstance(input_data, dict): raise ValueError(input_data must be dict) # 2. 业务逻辑示例调用Vertex AI try: # 所有网络请求必须设timeout response requests.post( fhttps://{REGION}-aiplatform.googleapis.com/v1/projects/{PROJECT_ID}/locations/{REGION}/endpoints/{ENDPOINT_ID}:predict, headers{Authorization: fBearer {get_access_token()}}, json{instances: [input_data[prompt]]}, timeout25 # 留5秒给sidecar处理 ) response.raise_for_status() # 3. 输出构造必须是原生dict result { generated_text: response.json()[predictions][0][content], model_used: gemini-pro } # 4. 日志记录仅记录关键信息避免敏感数据 logger.info(fSkill executed successfully for prompt: {input_data[prompt][:50]}...) return result except requests.exceptions.Timeout: logger.error(Vertex AI request timed out) raise except Exception as e: logger.error(fSkill execution failed: {str(e)}) raise def get_access_token() - str: 从GKE metadata server获取短期token # 这是Workload Identity的标准用法 metadata_url http://metadata.google.internal/computeMetadata/v1/instance/service-accounts/default/token response requests.get( metadata_url, headers{Metadata-Flavor: Google}, timeout5 ) response.raise_for_status() return response.json()[access_token]注意execute()方法里禁止导入全局变量或模块级状态。Agent Platform可能并发调用同一skills的多个实例共享模块状态会导致竞态条件。所有状态必须在input_data里传递或写到/workspace的文件里。5.metadata.yaml是skills的身份证字段缺失会导致注册即失败metadata.yaml看起来只是个配置文件但它是skills在Agent Platform里的唯一身份标识。我见过客户因为metadata.yaml里少写了一个字段折腾了两天。最典型的是version字段——很多人以为可以省略结果gcloud aiplatform skills create直接报错MISSING_REQUIRED_FIELD: version。原因在于Agent Platform用version做灰度发布控制同一skills名称下不同version对应不同GKE Deployment平台根据流量权重路由请求。metadata.yaml的字段不是随意定义的它对应google.cloud.aiplatform_v1beta1.Skill的Protobuf定义。我提取了所有必需字段及其约束字段类型是否必需示例说明namestring是code_review_v2skills唯一标识符只能含小写字母、数字、短横线长度1-63字符versionstring是1.2.0语义化版本格式MAJOR.MINOR.PATCH用于灰度发布display_namestring否Code Review Assistant控制台显示名称支持空格和中文descriptionstring否Reviews GitHub PRs using Gemini技能描述最大500字符skill_specobject是见下方技能规格定义labelsmapstring, string否{team: devops, env: prod}用于资源分组和监控其中skill_spec是嵌套对象必须包含skill_spec: # 必需指向schema.json的相对路径 schema_path: schema.json # 必需指向skill.py的相对路径 main_module_path: skill.py # 必需Python包入口函数名 entry_point: execute # 可选但强烈建议资源需求 resources: cpu_limit: 2 memory_limit: 4Gi # storage必须声明否则/workspace挂载失败 storage: 2Gi最容易被忽略的是storage字段。/workspace目录是GKE PVC挂载点storage声明的大小必须大于skills运行时所需的最大磁盘空间。我有个data_export技能要导出10GB CSVstorage设成1Gi结果执行到一半报错No space left on device。修复方案是把storage改成12Gi并确保GKE集群的StorageClass支持动态扩容。另一个致命错误是name字段冲突。Agent Platform要求name在项目内全局唯一。如果你注册了name: code_review的v1.0.0再注册同名的v1.1.0平台不会覆盖而是创建新版本。但如果你删掉v1.0.0再注册v1.1.0name还是code_review只是版本变了。问题在于Agent Platform不支持删除skills。gcloud aiplatform skills delete命令不存在。你只能停用deactivate某个版本但name永远被占用。所以命名策略必须前置规划用team-name-skill格式比如infra-terraform-plan、ml-feature-store-export避免用泛化的code_review。最后metadata.yaml必须放在skills目录的根路径。gcloud命令会递归扫描目录但只认根目录下的metadata.yaml。我把metadata.yaml放到skills/code_review/metadata.yaml结果命令报错METADATA_FILE_NOT_FOUND——它只在skills/目录下找不进子目录。提示用gcloud aiplatform skills validate --skill-dir ./skills提前校验metadata.yaml。这个命令会检查所有字段类型、格式和必填性比直接create快得多。我把它加进了CI流水线每次PR提交都自动运行。6. 调试skills不是看日志而是追踪sidecar容器的三重上下文流当你在GKE上部署skills后发现它不工作第一反应肯定是kubectl logs。但90%的情况下主容器日志是空的或者只有一行Starting skill server...。这是因为skills的执行上下文被sidecar容器接管了。真正的执行日志、网络请求、错误堆栈全在sidecar里。我画过一张调试流程图但按要求不能用Mermaid所以我用文字还原第一重上下文sidecar的/healthz探针流skills Pod启动后kubelet每5秒调用curl http://localhost:8080/healthz。如果返回非200Pod状态变成CrashLoopBackOff。但sidecar的/healthz不只是检查进程存活它还验证schema.json是否可解析、skill.py是否能import、metadata.yaml字段是否合法。所以CrashLoopBackOff不一定代表代码错误可能是metadata.yaml里version格式不对。第二重上下文sidecar的/execute代理流当Agent Platform调度skills时请求发到http://[POD_IP]:8080/executesidecar拦截后做三件事解析X-Request-ID头生成唯一trace ID校验input_data是否符合schema.json定义这里会爆出INVALID_INPUT_SCHEMA将清洗后的输入转发给主容器的/execute端点所以如果你看到400 Bad Request先kubectl logs [POD_NAME] -c sidecar-agent-runtime搜索INPUT_VALIDATION_FAILED。第三重上下文主容器的/execute执行流主容器收到sidecar转发的请求后才真正执行skill.py的execute()方法。这里的日志才是业务逻辑日志。但注意sidecar会截断超过1MB的日志所以logging.info()不要打大对象。我习惯用logging.debug()打关键变量用logging.info()只打状态摘要。实战调试步骤我总结成四步法确认Pod状态kubectl get pods -n aiplatform如果状态不是Running跳到第2步如果是Running但技能不响应跳到第3步。检查sidecar健康探针kubectl logs [POD_NAME] -c sidecar-agent-runtime | grep healthz如果看到Health check failed: invalid schema说明schema.json有问题如果看到Health check failed: module not found说明skill.py路径错了。捕获sidecar代理日志kubectl logs [POD_NAME] -c sidecar-agent-runtime --since1h | grep -A 5 -B 5 EXECUTE_REQUEST这会显示每次请求的输入、输出、耗时。如果看到INPUT_VALIDATION_FAILED复制input_data到本地用jsonschema.validate()验证。分析主容器执行日志kubectl logs [POD_NAME] -c skill-container --since10m如果这里报TimeoutError检查execute()里requests.timeout是否小于30如果报PermissionError检查/workspace挂载是否成功kubectl exec [POD_NAME] -- ls /workspace。最后分享一个技巧在skill.py里加一行logging.info(fEnvironment: {dict(os.environ)})能快速确认Workload Identity的token是否注入成功。如果GOOGLE_APPLICATION_CREDENTIALS环境变量为空说明Workload Identity没配好。7. 从“skills下载平台”迷思到生产级技能治理的落地路径搜索“skills下载平台有哪些”“skills大全”时你其实是在寻找一种能力复用范式。但现实是Agent Platform没有官方skills市场也不鼓励直接下载他人skills。原因很实在——skills不是npm包它绑定具体的GCP项目、GKE集群、Vertex AI端点和IAM权限。你下载一个github-pr-reviewerskills里面metadata.yaml写的project_id: my-company-123456endpoint_id: 1234567890123456789service_account: pr-reviewermy-company-123456.iam.gserviceaccount.com这些全得替换成你自己的值。手动替换12处配置不如重写。真正的技能治理是建立组织级的skills CI/CD流水线。我在三个客户那里落地的方案核心就三点第一统一skills模板仓库用GitHub私有仓库存skills-template包含标准目录结构skills-template/ ├── .github/workflows/ci.yml # 自动校验schema.json、metadata.yaml ├── scripts/ # 部署脚本 │ ├── build.sh # 构建OCI镜像 │ └── deploy.sh # gcloud skills create ├── skills/ # 示例skills │ ├── hello_world/ │ │ ├── schema.json │ │ ├── skill.py │ │ └── metadata.yaml │ └── ... └── README.md # 开发者指南所有团队新建skills都git clone这个模板改skills/[NAME]/目录即可。CI流水线会自动运行jsonschema校验、yamllint检查、gcloud aiplatform skills validate。第二skills版本化与灰度发布在metadata.yaml里强制version字段用Git Tag管理。CI流水线检测到git tag v1.2.0就自动执行gcloud aiplatform skills create \ --locationus-central1 \ --display-nameCode Review v1.2.0 \ --skill-dir./skills/code_review \ --versionv1.2.0然后用gcloud aiplatform agents update把Agent的skills引用从v1.1.0切到v1.2.0流量100%切换前先设5%灰度。第三skills监控与告警在GKE集群里部署Prometheus抓取sidecar容器的指标aiplatform_skill_execution_duration_secondsP99耗时aiplatform_skill_execution_errors_total按error_code标签分组aiplatform_skill_pod_statusPod Ready状态告警规则很简单如果aiplatform_skill_execution_errors_total{error_codeTIMEOUT} 5持续5分钟就触发PagerDuty。比看日志快得多。所以当你看到“今天学会了skills”“打开新世界”这类搜索背后的真实需求不是学一个技术名词而是想建立一套可复用、可审计、可监控的能力交付体系。skills只是载体真正的价值在治理流程里——模板标准化降低入门门槛CI/CD保障质量一致性灰度发布控制风险监控告警实现闭环运维。最后分享一个血泪教训别在skills里硬编码API密钥。我见过客户把Gemini API Key写进skill.py结果Git提交泄露Key被轮询盗用。正确做法是用Secret Manager存储skills启动时用Workload Identity读取from google.cloud import secretmanager_v1 def get_api_key() - str: client secretmanager_v1.SecretManagerServiceClient() name fprojects/{PROJECT_ID}/secrets/gemini-api-key/versions/latest response client.access_secret_version(namename) return response.payload.data.decode(UTF-8)这样Key只在内存里存在不落盘不进日志符合企业安全审计要求。