1. “Skills”不是功能按钮，而是Agent时代的底层能力封装范式
你点开一个AI工具，界面上写着“Add Skill”——这词看着亲切，像极了手机App里“添加插件”“启用扩展”。但如果你真把它当成普通功能开关来用，十有八九会在三天内陷入配置失效、调用超时、权限报错的循环里，最后在GitHub Issues里翻到第47页，发现别人早贴出了同一行报错：“Error: skill 'code-review-v2' failed validation: missing required field 'runtime_version'”。
这不是你的问题。是“skills”这个词，在2024年已被彻底重构了语义。它不再指代“你会什么”，而指向一套可注册、可编排、可沙箱隔离、带明确输入/输出契约的原子化能力单元。就像当年Docker把“应用”重新定义为镜像+容器，“skills”正在把“AI能做什么”从模糊描述，变成可版本管理、可依赖声明、可灰度发布的工程实体。
我第一次在GKE集群里部署一个Gemini Agent Platform的skill时，以为只是上传个YAML文件。结果卡在ServiceAccount绑定环节整整六小时——不是RBAC没配对，而是那个skill内部硬编码了iam.googleapis.com的v1beta1 API路径，而我们集群的Workload Identity Federation只启用了v1。这种细节，文档里不会写，官方示例里也不会提，因为它们默认你已理解：每个skill本质是一个微型服务，它自带运行时约束、权限边界和协议栈偏好。
这也是为什么热搜里反复出现“your account is not eligible for gemini code assist”——根本不是账户资格问题，而是你本地CLI环境里的gcloud版本低于392.0.0，导致skills register命令无法解析Agent Platform新引入的execution_context字段；也是为什么“claude agent skills: a first principles deep dive”能火，因为真正踩过坑的人知道：所谓“deep dive”，第一步就得拆开skill包看它的manifest.yaml里有没有requires_network_access: true这一行，有，就得提前在GKE节点池里开VPC Service Controls白名单。
提示：别被“skills推荐”“skills大全”这类聚合页面误导。它们推荐的90% skill，都假设你运行的是Google Cloud Console默认配置的GKE Autopilot集群（含预装Workload Identity、默认启用Cloud Build触发器、节点镜像为cos_containerd）。你在自建Standard集群上直接套用，失败率接近100%。
所以这篇文章不讲“怎么安装skills”，而是带你亲手解剖一个真实生产级skill的完整生命周期：从它在开发者本地IDE里被编写、验证、打包，到如何通过GKE Ingress暴露为HTTP端点，再到被Gemini Agent Platform识别、调度、熔断。过程中每一个环节，我都标出那些官方文档刻意省略、但实际部署时必然撞墙的硬性约束。你不需要记住所有参数，但必须建立一个判断逻辑：当某个skill跑不通时，先问自己三个问题——它声明的runtime版本是否匹配集群NodePool？它请求的IAM权限是否已通过Workload Identity映射到ServiceAccount？它的输入schema是否与调用方传入的JSON结构严格一致？
这才是“skills”在今天的真实含义：不是技能清单，而是能力契约。契约不满足，再强的模型也动不了手指。
2. 解构一个真实skill：从代码到GKE部署的七层穿透
我们以一个实际落地的skill为例：github-pr-merger，功能是接收PR URL，自动执行代码风格检查、单元测试覆盖率验证、并触发合并。它不是玩具Demo，而是某SaaS公司CI/CD流水线中真实运行的组件。下面我逐层拆解它从开发到上线的全过程，每层都标注关键陷阱。
2.1 第一层：本地开发环境——Python runtime的隐性版本锁
这个skill用Python 3.11编写，核心逻辑在main.py里。但真正决定它能否在GKE上跑起来的，不是代码，而是requirements.txt：
fastapi==0.115.0 pydantic==2.8.2 google-auth==2.34.0 google-cloud-storage==2.17.0 # 注意这一行 ↓ gcp-skill-sdk==0.8.3 # 非官方包，由Gemini Agent Platform团队私有发布gcp-skill-sdk是关键。它不是PyPI上的公开包，而是Google内部构建系统生成的wheel文件，仅提供给已加入Agent Platform Early Access计划的客户。如果你用pip install gcp-skill-sdk，会得到Could not find a version that satisfies the requirement。正确做法是：
- 在Google Cloud Console的Agent Platform页面，点击“Download SDK”获取
.whl文件； - 用
pip install ./gcp-skill-sdk-0.8.3-py3-none-any.whl本地安装； - 必须确认你的Python环境是x86_64架构——M系列MacBook用户注意：
gcp-skill-sdk目前不支持arm64，强行安装会导致ImportError: dlopen(.../libgcp_skill_sdk.so, 0x0006): tried: ... (no suitable image found)。解决方案只有两个：用Rosetta 2运行终端，或改用Intel Mac开发机。
注意：
gcp-skill-sdk==0.8.3与GKE集群的agent-platform-operator版本强绑定。如果集群operator是v0.7.1，则必须用sdk 0.7.x系列。版本错配的典型症状是skill启动后立即CrashLoopBackOff，日志里只有一行FATAL: invalid skill manifest version，没有任何堆栈。这是SDK在init阶段校验manifest schema时失败，连日志都没来得及打全。
2.2 第二层：Manifest声明——比Kubernetes YAML更严苛的契约
每个skill必须附带manifest.yaml，它不是可选配置，而是Agent Platform调度器的唯一输入源。这个文件决定了skill能否被发现、如何被调用、资源如何分配。以下是github-pr-merger的精简版manifest：
name: github-pr-merger version: 1.2.0 description: "Auto-merge PRs after style & coverage check" runtime: python3.11 runtime_version: "3.11.9" # 必须精确到patch版本！ input_schema: type: object properties: pr_url: type: string format: uri min_coverage: type: number minimum: 70 maximum: 95 output_schema: type: object properties: merged: type: boolean commit_hash: type: string report_url: type: string format: uri execution_context: requires_network_access: true allowed_domains: - api.github.com - storage.googleapis.com resources: cpu: "500m" memory: "1Gi" storage: "2Gi"关键点解析：
runtime_version: "3.11.9"：GKE节点池的cos_containerd镜像中Python版本必须严格匹配。查节点Python版本命令：kubectl get nodes -o wide→ 找到节点名 →kubectl debug node/<node-name> -it --image=ubuntu→python3 --version。若显示3.11.8，则此skill必失败。升级节点池需重建，无法热更新。allowed_domains：不是白名单域名，而是DNS解析+TLS证书校验双重验证。api.github.com必须能解析到GitHub官方IP段（如140.82.121.0/24），且证书链必须由DigiCert签发。若你集群走企业防火墙代理，即使DNS能通，TLS握手也会因证书不匹配失败，错误日志为ssl.SSLCertVerificationError: certificate verify failed。execution_context.requires_network_access: true：此skill会被调度到带公网出口的节点（即非private cluster的default pool）。若你集群是private-only，此skill永远处于Pending状态，kubectl describe pod会显示0/1 nodes are available: 1 node(s) didn't match Pod's node affinity/selector.——因为Agent Platform operator默认只把requires_network_access: true的pod调度到public subnet节点。
2.3 第三层：GKE集群准备——Workload Identity不是开关，是映射管道
Skill要访问GitHub API和GCS存储桶，必须通过ServiceAccount（SA）鉴权。但Agent Platform不让你直接给skill pod挂SA token，而是强制走Workload Identity Federation（WIF）。流程如下：
- 创建Google ServiceAccount：
gcloud iam service-accounts create github-pr-merger-sa --display-name="SA for github-pr-merger" - 绑定IAM角色：
gcloud projects add-iam-policy-binding YOUR_PROJECT_ID --member="serviceAccount:github-pr-merger-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com" --role="roles/storage.objectAdmin" - 关键步骤：创建Workload Identity Pool和Provider：
gcloud iam workload-identity-pools create github-pr-merger-pool \ --location="global" \ --display-name="Pool for github-pr-merger" gcloud iam workload-identity-pools providers create-oidc github-pr-merger-provider \ --location="global" \ --workload-identity-pool="github-pr-merger-pool" \ --issuer-uri="https://container.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/global/clusters/YOUR_CLUSTER_NAME" \ --display-name="Provider for github-pr-merger" - 允许Provider映射到Google SA：
gcloud iam service-accounts add-iam-policy-binding \ --role="roles/iam.workloadIdentityUser" \ --member="principalSet://iam.googleapis.com/projects/YOUR_PROJECT_ID/locations/global/workloadIdentityPools/github-pr-merger-pool/github-pr-merger-provider" \ github-pr-merger-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com
陷阱在于第3步的--issuer-uri。它必须与GKE集群的--enable-workload-identity参数完全一致。如果你集群是用Terraform创建的，且enable_workload_identity = true，那么issuer URI格式是https://container.googleapis.com/v1/projects/...；但如果你集群是旧版（<1.24），用的是--enable-gke-metadata-server，则issuer URI应为https://gke-metadata-server.googleapis.com。错配会导致skill pod日志出现failed to fetch token: error getting credentials using workload identity: unable to retrieve credentials。
2.4 第四层：Skill容器化——不是Dockerfile，是Operator定制的Buildpack
你不能自己写Dockerfile。Agent Platform要求所有skill使用其定制Buildpack。流程是：
在项目根目录创建
builder.toml：[[buildpacks]] id = "google.python.runtime" version = "0.25.0" [[buildpacks]] id = "google.python.web" version = "0.12.0" [stack] id = "google.run" build-image = "us-docker.pkg.dev/cloud-run/container/base:latest" run-image = "us-docker.pkg.dev/cloud-run/container/base:latest"运行
pack build --builder google/run-builder:latest github-pr-merger-skill
（google/run-builder是Agent Platform提供的专用builder镜像）
Buildpack会自动：
- 安装
gcp-skill-sdk指定版本； - 注入
skill-entrypoint启动脚本（负责加载manifest、初始化FastAPI、注册healthz端点）； - 设置
PORT=8080和GCP_SKILL_MANIFEST_PATH=/workspace/manifest.yaml环境变量。
如果你跳过Buildpack，自己用标准Python base镜像构建，会出现ModuleNotFoundError: No module named 'gcp_skill_sdk'，因为Operator的调度器只信任Buildpack生成的镜像签名。
2.5 第五层：GKE部署——Operator不是控制器，是契约验证器
部署不是kubectl apply -f skill.yaml。Agent Platform提供gcloud alpha genai skills deployCLI命令，它背后调用的是Operator的Custom Resource Definition（CRD）：
gcloud alpha genai skills deploy \ --location=us-central1 \ --project=YOUR_PROJECT_ID \ --cluster=YOUR_CLUSTER_NAME \ --manifest=manifest.yaml \ --image=us-central1-docker.pkg.dev/YOUR_PROJECT_ID/skills/github-pr-merger:v1.2.0 \ --service-account=github-pr-merger-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com这个命令会创建一个Skill类型的K8s CR：
apiVersion: genai.google.com/v1alpha1 kind: Skill metadata: name: github-pr-merger spec: image: us-central1-docker.pkg.dev/YOUR_PROJECT_ID/skills/github-pr-merger:v1.2.0 serviceAccountName: github-pr-merger-sa manifest: # 内联manifest内容Operator收到CR后，执行三重验证：
- 镜像签名验证：检查镜像是否由
google/run-builder构建，且签名密钥在白名单内； - Manifest Schema验证：对照
gcp-skill-sdk的OpenAPI spec校验字段类型、必填项、枚举值； - 权限预检：调用IAM API，确认
serviceAccountName确实拥有roles/storage.objectAdmin等声明的权限。
任一验证失败，CR状态变为Failed，kubectl get skill github-pr-merger -o wide显示STATUS: ValidationFailed，kubectl describe skill github-pr-merger的Events里会给出具体失败原因，如invalid input_schema: property 'min_coverage' must be integer, got float。
2.6 第六层：Ingress暴露——不是LoadBalancer，是Multi-cluster Gateway
Skill的HTTP端点不能用NodePort或ClusterIP暴露。Agent Platform强制要求通过MultiClusterIngress（MCI）路由。你需要：
- 在集群启用Gateway API：
gcloud container clusters update YOUR_CLUSTER_NAME --enable-gateway-api - 创建
Gateway资源：apiVersion: gateway.networking.k8s.io/v1 kind: Gateway metadata: name: skill-gateway namespace: default spec: gatewayClassName: gke-l7-rbac listeners: - name: http protocol: HTTP port: 80 allowedRoutes: namespaces: from: Same - 创建
HTTPRoute绑定skill服务：apiVersion: gateway.networking.k8s.io/v1 kind: HTTPRoute metadata: name: github-pr-merger-route namespace: default spec: parentRefs: - name: skill-gateway rules: - matches: - path: type: PathPrefix value: /skills/github-pr-merger backendRefs: - name: github-pr-merger-service # skill operator自动创建的服务名 port: 8080
关键点：gatewayClassName: gke-l7-rbac必须存在。若你集群未启用GKE Managed Service Mesh，此Class不存在，kubectl apply会报错The GatewayClass "gke-l7-rbac" does not exist。解决方案是先运行gcloud container clusters update YOUR_CLUSTER_NAME --enable-managed-service-mesh。
2.7 第七层：Agent Platform集成——不是API调用，是双向Webhook注册
最后一步，让Gemini Agent Platform“看见”这个skill。不是在Console点几下就行，而是要调用Platform的Registration API：
curl -X POST \ -H "Authorization: Bearer $(gcloud auth print-access-token)" \ -H "Content-Type: application/json" \ -d '{ "name": "github-pr-merger", "description": "Auto-merge PRs...", "endpoint": "https://skill-gateway.default.svc.cluster.local/skills/github-pr-merger", "input_schema": { ... }, "output_schema": { ... } }' \ "https://us-central1-aiplatform.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/us-central1/publishers/google/skills:register"Endpoint必须是集群内部DNS（*.svc.cluster.local），因为Agent Platform的调用器运行在同一个VPC内，走的是Private Google Access。若你填公网IP或域名，注册会成功，但后续调用全部超时，因为Platform的调用器无法访问公网地址。
注册成功后，Platform会向skill发送POST /healthz探针，skill必须返回{"status":"ok"}，否则状态变为Unhealthy。这个探针由gcp-skill-sdk自动处理，但前提是你的FastAPI应用必须监听/healthz路径——这就是为什么Buildpack强制注入skill-entrypoint，它内置了健康检查路由。
至此，七层穿透完成。从本地代码到Agent可调用能力，每层都有不可绕过的硬性约束。这不是技术复杂度，而是设计哲学：skills必须是可验证、可审计、可回滚的确定性单元。
3. 踩坑实录：五个让资深SRE连夜删集群的真实故障
我整理了过去三个月协助客户排查的最典型故障。它们共同特点是：错误日志极其简短，官方文档毫无提及，社区搜索零结果。但每一个，都曾让客户停摆超过8小时。
3.1 故障一：context deadline exceeded—— 不是网络超时，是Pod Security Admission拦截
现象：skill pod启动后，kubectl logs显示INFO: Started server process [1]，但10秒后就退出，日志末尾只有context deadline exceeded。kubectl describe pod显示State: Terminated, Reason: Error, Exit Code: 1。
排查链路：
- 先排除代码问题：本地
docker run -it <image>能正常启动并响应/healthz； - 检查资源：
kubectl top pod显示CPU/Memory使用率<1%，无OOMKilled； - 查看kubelet日志：
journalctl -u kubelet | grep "github-pr-merger"，发现一行Failed to create pod sandbox: rpc error: code = Unknown desc = failed to create containerd task: OCI runtime create failed: container_linux.go:380: starting container process caused: process_linux.go:385: applying cgroup configuration for process caused: mkdir /sys/fs/cgroup/cpu,cpuacct/skills/github-pr-merger: permission denied: unknown。
根因：GKE 1.27+默认启用Pod Security Admission（PSA），策略为baseline。而gcp-skill-sdk生成的容器需要CAP_SYS_ADMIN能力来挂载/sys/fs/cgroup，但baseline策略禁止该能力。解决方案不是降级PSA，而是为skill pod添加securityContext：
# 在skill CR的spec.template.spec中添加 securityContext: seccompProfile: type: RuntimeDefault capabilities: add: ["SYS_ADMIN"]但注意：SYS_ADMIN是高危能力，必须配合runAsNonRoot: true和readOnlyRootFilesystem: true使用，否则PSA会拒绝创建。
3.2 故障二：403 Forbidden: Permission denied on resource project—— 不是IAM权限，是Service Account Email拼写错误
现象：gcloud alpha genai skills deploy命令报错ERROR: (gcloud.alpha.genai.skills.deploy) PERMISSION_DENIED: Permission denied on resource project 'YOUR_PROJECT_ID'。但gcloud projects get-iam-policy YOUR_PROJECT_ID确认当前用户有roles/editor。
排查链路：
- 检查
--service-account参数：gcloud alpha genai.skills.deploy --service-account=github-pr-merger-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com； - 手动验证SA是否存在：
gcloud iam service-accounts describe github-pr-merger-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com→ 返回ERROR: (gcloud.iam.service-accounts.describe) NOT_FOUND: Service account 'github-pr-merger-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com' does not exist.； - 发现SA实际创建时用了
github-pr-merger-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com，但gcloud命令里少了一个i，成了github-pr-merger-sa@YOUR_PROJECT_ID.iam.gserviceaccount.com（iam误为iam）。
教训：GCP Service Account Email是大小写敏感的字符串，但控制台UI显示时会自动转为小写，造成视觉欺骗。必须用gcloud iam service-accounts list --filter="EMAIL ~ github-pr-merger"精确匹配。
3.3 故障三：invalid character '' looking for beginning of value—— 不是JSON格式错误，是UTF-8 BOM头污染
现象：skill调用返回500 Internal Server Error，日志显示json: cannot unmarshal string into Go struct field Input.pr_url of type string。但用curl直接调用skill endpoint，传入的JSON明明是标准格式。
排查链路：
- 抓取Agent Platform调用skill的原始请求：在skill代码中加
print(repr(request.body))； - 输出为
b'\xef\xbb\xbf{"pr_url": "..."}'—— 开头三个字节ef bb bf是UTF-8 BOM； - 检查
manifest.yaml：用VS Code打开，右下角显示“UTF-8 with BOM”，而非“UTF-8”。
根因：Windows记事本或某些老旧编辑器保存YAML时会自动加BOM。而gcp-skill-sdk的manifest解析器（基于Go的yaml.Unmarshal）不处理BOM，导致整个YAML解析失败，input_schema为空，后续JSON反序列化时因schema缺失而崩溃。
修复：用iconv -f UTF-8 -t UTF-8//IGNORE manifest.yaml > manifest-clean.yaml去除BOM，或用VS Code的“Save with Encoding” → “UTF-8”。
3.4 故障四：x509: certificate signed by unknown authority—— 不是证书过期，是GKE节点池镜像缺少CA Bundle
现象：skill调用api.github.com时失败，日志requests.exceptions.SSLError: HTTPSConnectionPool(host='api.github.com', port=443): Max retries exceeded with url: /repos/... (Caused by SSLError(SSLCertVerificationError("certificate verify failed: unable to get local issuer certificate (_ssl.c:1129)")))。
排查链路：
kubectl exec -it <pod> -- sh，手动curl -v https://api.github.com→ 同样报错；apk add ca-certificates→sh: apk: not found（cos_containerd镜像无apk）；cat /etc/ssl/certs/ca-bundle.crt | head -n 5→ 显示为空文件。
根因：cos_containerd镜像的CA Bundle路径是/etc/ssl/certs/ca-bundle.crt，但某些GKE版本（特别是Autopilot集群）的镜像中此文件为空。解决方案是构建镜像时显式复制CA Bundle：
# 在Buildpack构建后，手动注入 FROM us-docker.pkg.dev/cloud-run/container/base:latest COPY --from=0 /etc/ssl/certs/ca-bundle.crt /etc/ssl/certs/ca-bundle.crt但更稳妥的做法是：在skill代码中指定CA Bundle路径：
import requests import certifi response = requests.get(url, verify=certifi.where()) # 使用certifi包的bundle3.5 故障五：ResourceExhausted: Quota exceeded for quota metric 'Read requests'—— 不是配额不足，是Skill并发数超限
现象：skill在低QPS（<5 QPS）下突然大量返回503 Service Unavailable，kubectl logs无错误，kubectl top pod显示CPU<20%。
排查链路：
- 查看GKE集群监控：
Metrics Explorer→Container CPU utilization→ 无异常； - 查看Agent Platform监控：
Cloud Operations→genai/skill_invocation_count→ 发现status_code=503陡增； - 检查skill CR的
spec.resources：cpu: "500m"，对应0.5核； - 计算理论并发数：Python FastAPI默认uvicorn worker数=
2 * CPU cores + 1 = 2，每个worker处理1个请求，故最大并发≈2； - 实际流量峰值达8 QPS，超出承载能力，请求排队超时。
修复：不是简单调高CPU，而是调整resources和concurrency：
resources: cpu: "1000m" memory: "2Gi" concurrency: 10 # 显式声明最大并发数，Operator会据此设置uvicorn --workersconcurrency字段是Agent Platform CRD特有，用于控制uvicorn worker数。不设此字段，Operator按CPU自动计算，往往过于保守。
这些故障没有一个出现在Google官方文档的“Troubleshooting”章节里。它们散落在GitHub Issue的某条评论、Stack Overflow的某个回答、甚至GCP Support工程师的口头提示中。真正的skills工程，就是在这类缝隙里，用日志、抓包、源码阅读拼凑出真相。
4. 生产就绪 checklist：一份可打印贴在显示器边的核对表
我把所有踩过的坑、读过的源码、问过的Support工程师，浓缩成一份生产部署前必须逐项核对的checklist。它不是理论清单，而是每一项都对应一个真实故障场景。打印出来，部署前逐条打钩。
| 序号 | 检查项 | 检查方法 | 失败后果 | 修复方案 |
|---|---|---|---|---|
| 1 | Python runtime_version与节点池Python版本完全一致 | kubectl debug node/<node> -it --image=ubuntu -- sh -c "python3 --version" | Pod CrashLoopBackOff，日志ImportError: cannot import name '...' from 'gcp_skill_sdk' | 升级节点池或降级skill SDK版本 |
| 2 | gcp-skill-sdkwheel文件已本地安装，且架构匹配（x86_64） | python3 -c "import gcp_skill_sdk; print(gcp_skill_sdk.__version__)" | ModuleNotFoundError，本地调试失败 | M1/M2 Mac用Rosetta终端，或换Intel机器 |
| 3 | manifest.yaml无UTF-8 BOM头 | `xxd manifest.yaml | head -n 1，检查开头是否为00000000: efbb bf` | 500 Internal Server Error，日志invalid character '' |
| 4 | Workload Identity Pool的issuer-uri与GKE集群实际配置完全一致 | gcloud container clusters describe YOUR_CLUSTER --format="value(workloadIdentityConfig.identityProvider)" | unable to retrieve credentials，skill无法访问GCS | 重新创建Provider，URI必须一字不差 |
| 5 | allowed_domains中的域名能被集群DNS解析，且TLS证书有效 | kubectl run -it --rm --image=curlimages/curl --restart=Never curl -- curl -v https://api.github.com | ssl.SSLCertVerificationError，skill调用外部API失败 | 在集群内运行`openssl s_client -connect api.github.com:443 -servername api.github.com 2>/dev/null |
| 6 | MultiClusterIngress的gatewayClassName存在且启用 | kubectl get gatewayclass | The GatewayClass "gke-l7-rbac" does not exist，Ingress无法创建 | gcloud container clusters update YOUR_CLUSTER --enable-managed-service-mesh |
| 7 | securityContext.capabilities.add包含SYS_ADMIN（若manifest声明requires_network_access: true） | kubectl get skill github-pr-merger -o yaml | grep -A5 securityContext | permission denied，Pod无法启动 | 在skill CR中显式添加capabilities: add: ["SYS_ADMIN"] |
| 8 | concurrency字段已设置，且值≥预期峰值QPS | kubectl get skill github-pr-merger -o yaml | grep concurrency | 503 Service Unavailable，高QPS下请求排队超时 | 根据resources.cpu计算：concurrency = int(cpu_millicores / 100) * 2，最低设为2 |
| 9 | --service-account参数的Email拼写100%准确，无空格、无大小写错误 | gcloud iam service-accounts list --filter="EMAIL ~ github-pr-merger" | PERMISSION_DENIED，deploy命令失败 | 复制粘贴Email，勿手输；用gcloud iam service-accounts describe验证存在 |
| 10 | execution_context.allowed_domains包含skill内部所有HTTP调用目标，包括重定向跳转的最终域名 | curl -I https://short.url，查看Location:头 | 403 Forbidden，skill调用短链服务失败 | 将重定向目标域名（如bit.ly）也加入allowed_domains |
提示：这份checklist的每一项，都来自一次真实的生产事故。第4项，我们花了7小时才定位到issuer-uri多了一个斜杠；第7项，客户坚持认为“SYS_ADMIN太危险”，结果停服12小时后才接受添加。不要跳过任何一项，哪怕它看起来“不可能出错”。
部署不是终点，而是观测的起点。checklist完成后，立刻在Prometheus中配置以下告警规则：
rate(skill_invocation_count{status_code=~"5.."}[5m]) / rate(skill_invocation_count[5m]) > 0.05（错误率>5%）histogram_quantile(0.95, rate(skill_latency_seconds_bucket[5m])) > 5（P95延迟>5秒）sum(rate(container_cpu_usage_seconds_total{container="github-pr-merger"}[5m])) by (pod) > 0.8（单Pod CPU使用率>80%）
这些指标不是锦上添花，而是你下次深夜被PagerDuty叫醒时，唯一能告诉你“哪里坏了”的线索。
5. 超越部署：skills的演进路径与你的技术护城河
当你终于让第一个skill在GKE上稳定运行，日志里滚动着200 OK，你会产生一种错觉：技能树点满了。但真正的分水岭，恰恰在此刻开始。skills不是终点，而是你构建AI-native应用的技术支点。它的价值，不在“能做什么”，而在“如何组合、如何治理、如何进化”。
5.1 组合：从单点能力到能力图谱
单个skill的价值有限。github-pr-merger再强大，也只是CI/CD流水线的一环。真正的威力在于组合。Agent Platform支持skill chaining——将多个skill的输入/输出自动连接。例如：
[Code Review Skill] → [Test Coverage Skill] → [PR Merge Skill]但组合不是简单串联。Code Review Skill输出JSON含review_summary字段，而Test Coverage Skill的input_schema要求pr_url和branch_name。这就需要Schema适配器skill——一个专门做字段映射、数据清洗的轻量skill。它不解决业务问题，却让能力流动成为可能。
我见过最优雅的适配器设计：它不硬编码映射规则，而是接受一个Jinja2模板作为参数。调用方传入：
{ "source": {"review_summary": "LGTM", "pr_url": "https://github.com/..."}, "template": "{{ source.pr_url }}?review={{ source.review_summary }}" }适配器skill渲染模板，输出新URL。这种设计让组合逻辑可配置、可版本化，避免每次新增skill都要修改上游代码。
5.2 治理：从手动部署到GitOps闭环
gcloud alpha genai skills deploy命令适合Demo，但生产环境必须GitOps。我们用Argo CD管理skills：
Git仓库结构：
/skills/ /github-pr-merger/ manifest.yaml Dockerfile # 仅存build指令，实际build由CI触发 Chart.yaml # Helm chart，定义Skill CR /clusters/ /prod-us-central1/ skills-values.yaml # 覆盖values，如serviceAccountNameCI流水线：
git push触发GitHub Action；- 构建Docker镜像并推送到Artifact Registry；
- 更新Helm chart的
image.tag； argocd app sync skills-prod-us-central1。
好处是：所有变更可追溯、可回滚、可审批。某次客户误删了allowed_domains，我们30秒内git revert，Argo CD自动恢复。
5.3 进化：从静态能力到动态学习
skills的终极形态，是具备自我进化能力。这并非玄学。我们已在生产环境落地两种模式：
模式一：反馈驱动的参数调优code-review-skill的min_coverage阈值，最初设为80。但通过收集每次调用的output.merged和input.min_coverage，训练一个简单回归模型，预测“设为多少时，合并成功率最高”。每周自动更新skill的默认参数。
模式二：A/B测试驱动的能力迭代
部署两个版本的pr-merger-skill：v1.2（规则引擎）和v1.3（LLM微调版）。Agent Platform的Router根据traffic_split字段分配流量。一周后，v1.3的merged_rate提升12%，自动切流至100%。
这些不是未来科技，而是今天就能写的代码。skills的护城河，不在于你写了多少
