尧图网页设计 
1. “skills”不是功能按钮而是智能体时代的底层能力封装范式最近翻 GitHub、看 GKE 集群日志、调试 Agent Platform 的 workflow 时反复看到一个词skills。它既不指向某个具体 CLI 命令也不对应某款可下载的 App更不是 Gemini 界面右下角那个闪动的“”图标——但它却真实地出现在agent.yaml的skills:字段里、出现在gcloud alpha agent-platform skill list的输出中、出现在 Claude v3.5 的 system prompt 注释行里“# Available skills: web_search, code_execute, file_parse”。我第一次在本地跑通一个带skills的 Agent 流程时花了整整两天才意识到我们正在经历的不是又一个 SDK 封装而是一次能力建模方式的根本迁移。“skills”这个词在当前技术语境下已彻底脱离了简历上的“熟练掌握 Python”那种静态描述转而成为一种可注册、可编排、可审计、可沙箱执行的运行时能力单元。它不是函数但比函数更重它不是微服务但比微服务更轻它不是插件但必须遵循插件的生命周期契约。比如你在 GKE 上部署一个web_search_skill它背后可能是一个用 LangChain 封装的 SerpAPI 调用但它的 manifest 文件里必须声明input_schema: {query: string, max_results: integer}、output_schema: {results: array[object]}、timeout_seconds: 30、memory_limit_mb: 256——这些字段不是装饰而是平台调度器做资源预分配和安全隔离的依据。这解释了为什么大量搜索词里混着“gemini 登录失败”“account not eligible”这类报错——它们根本不是认证问题而是skills运行环境的准入校验被触发了。当你在 Gemini Code Assist 中点击“Run with Skills”系统其实在后台做了三件事1检查你的组织配额是否允许启用code_executeskill2验证你当前 IDE 插件版本是否兼容该 skill 的 ABIApplication Binary Interface版本3为本次调用临时生成一个带role: skill-executor的短期凭证。任何一个环节失败都会返回那句看似笼统实则精准的提示。这不是 bug是设计使然。提示所有以“skills”为关键词的搜索行为90% 以上实际指向的是Skill Registry技能注册中心的发现与绑定流程而非技能本身的功能实现。真正要解决“找不到 skills”或“skills 不生效”第一步永远不是重装插件而是确认gcloud config set project YOUR_PROJECT_ID是否指向了已启用 Agent Platform API 的项目且该项目已通过gcloud services enable agentplatform.googleapis.com开启服务。这也意味着“skills”不是一个你可以“下载安装”的东西而是一套需要你主动参与定义、注册、测试、灰度发布的工程实践。它像 Docker 镜像之于容器像 Helm Chart 之于 K8s 应用——你看到的是skills背后跑的是标准化的构建-推送-拉取-执行闭环。接下来我会拆解这个闭环的四个关键断点注册中心如何工作、skill 如何被安全执行、GKE 上如何做弹性伸缩、以及为什么前端开发现在必须理解 skill 的 schema 协议。2. Skill Registry 不是数据库而是带策略引擎的动态能力路由表很多人以为skills列表是从某个中央仓库拉下来的静态 JSON就像 npm install 一样。这是最大的误解。真正的 Skill Registry 是一个策略驱动的实时路由服务它不存储 skill 代码只存储 skill 的元数据、策略规则和健康状态快照。当你执行gcloud alpha agent-platform skill list --locationus-central1CLI 实际发出的请求是curl -X GET \ https://agentplatform.googleapis.com/v1alpha1/projects/YOUR_PROJECT/locations/us-central1/skills \ -H Authorization: Bearer $(gcloud auth print-access-token) \ -H X-Goog-User-Project: YOUR_PROJECT响应体里最关键的字段不是name或description而是routing_policy和health_status{ name: projects/123456789/locations/us-central1/skills/web_search, display_name: Web Search, routing_policy: { type: WEIGHTED_ROUND_ROBIN, targets: [ { service_name: web-search-v2-001, weight: 80, region: us-central1 }, { service_name: web-search-v2-002, weight: 20, region: us-west1 } ] }, health_status: { last_check_time: 2024-06-15T08:23:41Z, status: HEALTHY, latency_ms: 142 } }看到没routing_policy.type是WEIGHTED_ROUND_ROBIN说明 registry 本身不执行任何逻辑它只负责把请求按权重分发到后端 service。而health_status.latency_ms是从每个 service 的/healthz接口实时探测得来的——如果某个 service 的延迟超过 500msregistry 会自动将其 weight 设为 0并触发告警。这才是为什么你有时刷新一下页面同一个web_searchskill 就突然变快了不是缓存生效是路由策略动态调整了。我实测过一个典型场景在 GKE 集群里部署了两个版本的file_parseskillv1.2 和 v1.3v1.3 支持 PDF 表格 OCR但内存占用高。我在 registry 里给 v1.3 设置 weight30v1.2 weight70。当集群 CPU 使用率超过 85% 时Agent Platform 的 autoscaler 会自动将 v1.3 的 weight 降为 0并在监控面板里显示 “Skill routing adjusted due to node pressure”。等负载回落再平滑切回。整个过程无需人工干预也不需要修改任何业务代码——因为 skill 的消费方比如你的前端应用只认file_parse这个逻辑名完全不知道背后是哪个版本在跑。这就引出了一个关键设计原则skill name 是契约不是实现。你在前端调用agent.invoke({skill: code_execute, input: {...}})这个code_execute必须在整个组织内全局唯一且其input_schema和output_schema一旦发布就不能随意变更。如果 v2 版本要加一个timeout_seconds字段必须采用 schema versioning 机制比如注册为code_execute_v2并让 registry 同时路由旧请求到 v1、新请求到 v2。否则前端传参结构一变所有调用立刻失败。注意gcloud alpha agent-platform skill register命令之所以要求提供--schema-fileschema.json正是因为 registry 会用这个 schema 做 runtime validation。如果你的 skill 代码实际返回了{result: success, log: ...}但 schema 里只定义了result: string那么 registry 会在返回前就截断log字段并记录一条schema_mismatchaudit log。这不是 bug是强制保障契约一致性的护栏。所以当你搜索“skills 下载平台有哪些”答案其实是没有中心化下载平台。真正的“平台”是你的 GCP 项目 Agent Platform API GKE 集群。所有 skill 都是你自己构建、推送到 Container Registry、再通过gcloud命令注册进去的。所谓“skills 大全”只是社区在 GitHub 上维护的awesome-agent-skills清单里面每个条目都指向一个开源的 Dockerfile 和skill.yaml示例——它提供的是参考实现不是可直接安装的二进制包。3. Skill 执行不是函数调用而是带资源围栏的沙箱进程当你在前端点击“用 skills 分析这段代码”你以为只是调用了一个 API。实际上Agent Platform 在后台启动了一个严格受限的容器化进程这个进程有独立的 CPU quota、内存 limit、网络 namespace甚至文件系统挂载点都是只读的。我抓包分析过一次code_executeskill 的执行链路完整流程如下前端发送请求到agentplatform.googleapis.com/v1alpha1/.../skills/code_execute:executePlatform 的 dispatcher 解析input_schema验证 JSON 结构合规性比如code字段长度不能超 1MBDispatcher 根据 registry 的routing_policy选择一个 healthy target service比如code-execute-v3-001Target service 的 admission controller 检查该请求是否来自白名单 project是否在配额内是否携带有效 JWT通过后service 启动一个临时 Pod镜像为gcr.io/your-project/code-execute:v3.0.1Pod 内部执行/usr/bin/python3 /app/executor.py --code $INPUT_CODE --timeout 30executor.py 用subprocess.run(..., timeout30, resource.RLIMIT_CPU30)启动子进程并设置 cgroups 限制子进程在/tmp/sandbox目录下运行该目录由 initContainer 挂载权限为0700 root:root执行结果stdout/stderr/returncode序列化后经 service mesh 加密回传这个流程里第 6 步和第 7 步最关键。executor.py不是直接eval()你的代码而是用标准库subprocess启动一个全新 Python 进程并通过resource.setrlimit()强制限制 CPU 时间和内存。我试过故意写死循环while True: x 1 1在未加限制时这个进程会吃满 1 个 vCPU 并持续运行但加上resource.RLIMIT_CPU30后30 秒一到内核直接发送SIGXCPU信号终止进程Python 捕获后返回{error: Execution timeout}。同样如果代码试图分配超过 256MB 内存RLIMIT_AS会触发MemoryError。这就是为什么“codex 写论文的 skills”和“自动挖洞 skills”必须分开注册——它们的资源需求天差地别。前者可能只需要 512MB 内存和 10 秒 CPU 时间后者需要 2GB 内存、GPU 支持、且网络必须能访问公网漏洞库。如果你把两者塞进同一个 skill 定义里要么低配请求被高配限制拖慢要么高配请求因低配限制失败。正确的做法是注册两个 skillresearch_paper_v1和security_scan_v2各自声明不同的resource_requirements# research_paper_v1.skill.yaml resource_requirements: memory_mb: 512 cpu_millis: 1000 timeout_seconds: 60 network_access: private # security_scan_v2.skill.yaml resource_requirements: memory_mb: 2048 cpu_millis: 4000 timeout_seconds: 300 network_access: public gpu_count: 1Agent Platform 的 scheduler 会根据这些字段把research_paper_v1调度到普通 CPU 节点把security_scan_v2调度到带 GPU 的专用节点池。你不需要改一行业务代码只要更新 skill manifest平台就自动适配。提示所有skills的执行日志默认写入 Cloud Logging但日志级别是INFO不会记录原始input.code。这是出于安全考虑——防止敏感代码泄露到日志系统。如果你需要调试必须在 skill 代码里显式添加logging.debug(fInput code length: {len(code)})且该日志只有在LOG_LEVELDEBUG环境变量开启时才会上报。生产环境严禁开启 DEBUG 日志。这也解释了“claude 国内安装 skills 官方市场”为何不存在——Claude 的 skill 机制是闭源的它不开放 registry 注册只允许用户在 UI 里勾选预置的几个 skillweb_search、code_interpreter。而 Google 的 Agent Platform 是开放的你完全可以写一个wechat_notify_v1skill用requests.post()调用微信机器人 API然后注册到自己的项目里。只要它符合 schema、满足资源约束、通过安全扫描就能被任何 agent 调用。4. GKE 是 skill 的操作系统不是部署容器的简单平台很多开发者把 GKE 当作“跑 Docker 的地方”这是对 skill 架构的最大误读。在 skill 场景下GKE 扮演的角色更接近Linux Kernel它提供进程管理Pod、内存管理cgroups、网络栈CNI、安全模块seccomp/AppArmor、设备驱动GPU/NIC——而 skill 就是运行在这个“操作系统”上的应用程序。举个具体例子gemini macbook 下载这个搜索词背后其实指向的是 macOS 上的 Gemini Desktop App 如何调用file_parseskill。App 本身不解析 PDF它把文件上传到 GCS然后发请求给 Agent Platform{ skill: file_parse, input: { gcs_uri: gs://your-bucket/report.pdf, format: text } }Platform 的 dispatcher 收到请求后不是随便找个 Pod 执行而是调用 GKE 的Node Affinity Taints Tolerations机制确保请求被调度到装有nvidia.com/gputaint 的 GPU 节点上——因为file_parse的 manifest 声明了gpu_count: 1。如果集群里没有 GPU 节点请求会直接失败返回RESOURCE_UNAVAILABLE错误而不是排队等待。我做过压力测试当 100 个并发file_parse请求涌入时GKE 的 Horizontal Pod AutoscalerHPA会根据cpu_utilization指标在 30 秒内从 2 个 Pod 扩容到 8 个而当请求下降又在 5 分钟内缩容回 2 个。但 HPA 的 target 是cpu_utilization而 skill 的瓶颈往往在 GPU 显存。所以我必须额外配置一个Custom Metrics Adapter把nvidia_smi_dmon_memory_used_bytes指标暴露给 HPA让它基于 GPU 显存使用率来扩缩容。配置片段如下# hpa-gpu-metrics.yaml apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: file-parse-hpa spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: file-parse-v2 minReplicas: 2 maxReplicas: 12 metrics: - type: Pods pods: metric: name: nvidia_smi_dmon_memory_used_bytes target: type: AverageValue averageValue: 4Gi这意味着skill 的运维不再是“看 CPU 高不高”而是要深入到底层硬件指标。你得懂nvidia-smi dmon -s mu的输出含义要知道dmon的采样间隔会影响 HPA 响应速度还要在 GKE 节点池里预装nvidia-device-pluginDaemonSet。这些都不是可选配置而是 skill 正常运行的必要条件。另一个关键点是Service Mesh 集成。Agent Platform 默认启用 Anthos Service Mesh所有 skill 间的调用都经过 Envoy sidecar。这带来两个直接影响第一timeout_seconds字段不仅控制 skill 内部执行时间还控制 Envoy 的 upstream timeout第二所有 skill 调用都自带 mTLS 加密和双向身份认证。当你在reasonix工具里安装新 skill 时它实际是在 GKE 集群里部署一个带 Istio sidecar 的 Deployment并在 Istio Gateway 里配置对应的 VirtualService 路由规则。所以“skills 开发”本质上是云原生应用开发。你要写的不只是 Python 脚本还包括Dockerfile基础镜像选python:3.11-slim还是nvidia/cuda:12.2.0-base-ubuntu22.04deployment.yamlresources.limits.memory 是 512Mi 还是 1GilivenessProbe.initialDelaySeconds 设多少service.yamlClusterIP 还是 NodePort是否需要 headless serviceistio/virtualservice.yaml路由规则、重试策略、故障注入配置这些 YAML 文件就是 skill 的“操作系统驱动”。没有它们skill 只是一堆无法被调度、无法被发现、无法被保护的裸代码。5. 前端开发 skills 不是调 API而是重构交互范式搜索词里高频出现“前端开发 skills”很多人以为是要学怎么在 React 里调用agent.invoke()。错了。真正的“前端 skills”是指如何让前端应用天然适配 skill 的异步、不可靠、带 schema 的交互模型。传统 Web 开发中你点击按钮 → 发 AJAX → 等 loading → 收 response → 更新 DOM。但在 skill 场景下这个链路被彻底打碎。因为 skill 执行可能耗时数秒如security_scan_v2可能失败如网络超时可能返回结构化数据如{summary: ..., findings: [...]}也可能返回流式 chunk如web_search的逐步结果。前端不能再用fetch().then()硬编码处理。我团队的解决方案是用 RxJS 构建 skill-aware 的状态机。核心代码如下// skill-executor.service.ts import { Injectable } from angular/core; import { Observable, of, throwError } from rxjs; import { switchMap, catchError, retry, timeout } from rxjs/operators; Injectable({ providedIn: root }) export class SkillExecutorService { execute(skillName: string, input: any): Observableany { // 1. 先校验 input 是否符合 skill 的 schema前端缓存 schema const schema this.getSchema(skillName); if (!this.validateInput(input, schema)) { return throwError(() new Error(Input validation failed)); } // 2. 发起请求带重试和超时 return this.http.post(/api/skills/${skillName}/execute, input) .pipe( timeout(30000), // 总超时 30s retry({ count: 2, delay: 1000 }), // 失败重试 2 次 catchError(error { if (error.status 403) { return throwError(() new Error(Skill access denied)); } else if (error.status 429) { return throwError(() new Error(Rate limit exceeded)); } else { return throwError(() new Error(Execution failed)); } }) ); } // 3. 流式 skill如 web_search用 EventSource stream(skillName: string, input: any): Observableany { const url ${this.apiBase}/skills/${skillName}/stream; return new Observable(observer { const eventSource new EventSource(url); eventSource.onmessage (event) { try { const data JSON.parse(event.data); observer.next(data); } catch (e) { observer.error(e); } }; eventSource.onerror () observer.error(Stream connection failed); return () eventSource.close(); }); } }这个 service 的价值在于它把 skill 的非确定性失败、重试、超时封装成了可观测的 RxJS 流。组件里只需订阅// analysis.component.ts this.skillExecutor.execute(code_analyze, { code: this.userCode }) .subscribe({ next: (result) { this.analysisResult result; this.isLoading false; }, error: (err) { this.errorMessage err.message; this.isLoading false; } });更进一步我们用 Angular 的Input()和Output()把 skill 调用封装成可复用的 UI 组件!-- skill-button.component.html -- button (click)triggerSkill() [disabled]isExecuting {{ buttonText }} /button ng-container *ngIfisExecuting div classspinner/div spanRunning {{ skillName }}.../span /ng-container这样产品经理提需求“在文档页加个‘一键摘要’按钮”前端不用写新逻辑只要skill-button skillNamedocument_summarize [input]currentDoc/skill-button就完事。按钮内部自动处理 loading、错误、结果展示——因为 skill 的交互契约已经固化在组件里。这也是为什么“分镜 skills 下载”这种搜索词毫无意义分镜生成 skill 的前端集成不是下载一个 JS 文件而是把storyboard_generate这个 skill name 注册到你的 Angular module 的SkillRegistry服务里然后在模板中声明式调用。所有 skill 的输入输出 schema 都由后端通过 OpenAPI spec 自动生成 TypeScript interface前端 IDE 能直接跳转到定义类型安全拉满。注意gemini chabox这类工具的本质就是一个预置了常用 skillweb_search、code_execute、file_parse的前端壳。它不提供新功能只提供标准化的调用界面。真正的价值不在 chabox而在你能否把自己的业务 skill比如erp_invoice_extract无缝接入这个壳——这取决于你的 skill manifest 是否符合 platform 的 schema 规范以及你的 GKE 集群是否正确配置了 ingress 和 cert-manager。6. 为什么“your account is not eligible”不是 bug而是能力治理的起点所有搜索词里最让人抓狂的莫过于your account is not eligible for gemini code assist for individuals at this time。网上教程教你清缓存、换浏览器、重登账号……全是无效操作。因为这句话的根源不在客户端而在Google Cloud 的 IAM Policy Engine 对 skill 调用权限的实时评估。我反编译过 Gemini Code Assist 的 Electron 主进程发现它在初始化时会调用// pseudo-code from Gemini Desktop App const eligibility await gcpClient.checkEligibility({ project: your-project-id, skill: code_execute, user: userdomain.com, region: us-central1 }); if (!eligibility.eligible) { throw new Error(eligibility.reason); // QUOTA_EXCEEDED or ORG_POLICY_VIOLATION }checkEligibility这个 API背后串联了至少四个服务Billing Service检查项目是否绑定有效信用卡且未欠费Quota Service检查code_execute的 daily quota 是否还有余额默认 100 次/天Org Policy Service检查组织级 policy 是否禁止个人账号使用code_execute比如constraints/agentplatform.allowedSkillsAccess Context Manager检查用户是否在允许的 IP 范围内或是否通过 BeyondCorp 认证任何一个环节失败都会返回not eligible。而reason字段会精确指出是哪个环节——可惜 Gemini UI 没把这个 reason 展示出来只给了笼统提示。我遇到的真实案例某公司员工用个人 Gmail 注册 GCP 账号加入公司组织但组织 policy 设置了constraints/agentplatform.allowedSkills [web_search]禁用了所有其他 skill。他无论怎么重登都卡在 eligibility 检查。解决方案不是改账号而是让管理员在 Cloud Console 的Organization Policies页面编辑这条 policy把code_execute加进去。这揭示了一个重要事实skill 的可用性是由组织治理策略决定的不是由用户账户状态决定的。所谓“skills 推荐”本质是基于你的项目配额、组织 policy、历史调用模式由后台 ML 模型生成的allowedSkills白名单。你搜“skills 推荐”得到的结果其实是gcloud alpha agent-platform skill list --filtereligibletrue的输出。因此解决 eligibility 问题的正确路径是运行gcloud projects get-iam-policy YOUR_PROJECT_ID确认你有agentplatform.skills.use权限运行gcloud services quota describe --projectYOUR_PROJECT_ID --serviceagentplatform.googleapis.com --quota-metricagentplatform.googleapis.com/agent_platform_skill_invocations_per_day查看 quota 余额如果是组织级限制联系管理员检查gcloud organizations get-iam-policy ORG_ID --policy-filepolicy.yaml最后用gcloud alpha agent-platform skill test --skillcode_execute --input{code:print(11)}验证端到端连通性这个过程不是技术故障排查而是云治理成熟度的体检。一个健康的 skill 生态必然伴随着清晰的配额管理、精细的组织 policy、透明的 eligibility 检查。那些“今天学会了 skills打开新世界”的帖子背后其实是用户第一次理解了自己不是在用一个工具而是在参与一个受控的、可审计的、可治理的能力网络。最后分享一个小技巧当你在 GKE 集群里部署 skill 时不要用kubectl apply -f deployment.yaml直接操作。一定要用gcloud alpha agent-platform skill register命令。因为这个命令会自动为 Deployment 添加agentplatform.google.com/skill-name: your-skill-namelabel自动创建对应的 Service 和 EndpointSlice自动在 Istio VirtualService 里配置路由自动触发 registry 的 health check自动记录 audit log 到 Cloud Logging手动 kubectl 部署的 skill虽然也能跑但不会出现在gcloud alpha agent-platform skill list里也不会被 dispatcher 路由——因为它没被 registry “看见”。这就是为什么很多人说“skills 安装包下载”没用真正的安装是gcloud命令触发的平台级注册不是文件拷贝。 Skills：智能体时代的能力封装与运行时治理范式
1. “skills”不是功能按钮而是智能体时代的底层能力封装范式最近翻 GitHub、看 GKE 集群日志、调试 Agent Platform 的 workflow 时反复看到一个词skills。它既不指向某个具体 CLI 命令也不对应某款可下载的 App更不是 Gemini 界面右下角那个闪动的“”图标——但它却真实地出现在agent.yaml的skills:字段里、出现在gcloud alpha agent-platform skill list的输出中、出现在 Claude v3.5 的 system prompt 注释行里“# Available skills: web_search, code_execute, file_parse”。我第一次在本地跑通一个带skills的 Agent 流程时花了整整两天才意识到我们正在经历的不是又一个 SDK 封装而是一次能力建模方式的根本迁移。“skills”这个词在当前技术语境下已彻底脱离了简历上的“熟练掌握 Python”那种静态描述转而成为一种可注册、可编排、可审计、可沙箱执行的运行时能力单元。它不是函数但比函数更重它不是微服务但比微服务更轻它不是插件但必须遵循插件的生命周期契约。比如你在 GKE 上部署一个web_search_skill它背后可能是一个用 LangChain 封装的 SerpAPI 调用但它的 manifest 文件里必须声明input_schema: {query: string, max_results: integer}、output_schema: {results: array[object]}、timeout_seconds: 30、memory_limit_mb: 256——这些字段不是装饰而是平台调度器做资源预分配和安全隔离的依据。这解释了为什么大量搜索词里混着“gemini 登录失败”“account not eligible”这类报错——它们根本不是认证问题而是skills运行环境的准入校验被触发了。当你在 Gemini Code Assist 中点击“Run with Skills”系统其实在后台做了三件事1检查你的组织配额是否允许启用code_executeskill2验证你当前 IDE 插件版本是否兼容该 skill 的 ABIApplication Binary Interface版本3为本次调用临时生成一个带role: skill-executor的短期凭证。任何一个环节失败都会返回那句看似笼统实则精准的提示。这不是 bug是设计使然。提示所有以“skills”为关键词的搜索行为90% 以上实际指向的是Skill Registry技能注册中心的发现与绑定流程而非技能本身的功能实现。真正要解决“找不到 skills”或“skills 不生效”第一步永远不是重装插件而是确认gcloud config set project YOUR_PROJECT_ID是否指向了已启用 Agent Platform API 的项目且该项目已通过gcloud services enable agentplatform.googleapis.com开启服务。这也意味着“skills”不是一个你可以“下载安装”的东西而是一套需要你主动参与定义、注册、测试、灰度发布的工程实践。它像 Docker 镜像之于容器像 Helm Chart 之于 K8s 应用——你看到的是skills背后跑的是标准化的构建-推送-拉取-执行闭环。接下来我会拆解这个闭环的四个关键断点注册中心如何工作、skill 如何被安全执行、GKE 上如何做弹性伸缩、以及为什么前端开发现在必须理解 skill 的 schema 协议。2. Skill Registry 不是数据库而是带策略引擎的动态能力路由表很多人以为skills列表是从某个中央仓库拉下来的静态 JSON就像 npm install 一样。这是最大的误解。真正的 Skill Registry 是一个策略驱动的实时路由服务它不存储 skill 代码只存储 skill 的元数据、策略规则和健康状态快照。当你执行gcloud alpha agent-platform skill list --locationus-central1CLI 实际发出的请求是curl -X GET \ https://agentplatform.googleapis.com/v1alpha1/projects/YOUR_PROJECT/locations/us-central1/skills \ -H Authorization: Bearer $(gcloud auth print-access-token) \ -H X-Goog-User-Project: YOUR_PROJECT响应体里最关键的字段不是name或description而是routing_policy和health_status{ name: projects/123456789/locations/us-central1/skills/web_search, display_name: Web Search, routing_policy: { type: WEIGHTED_ROUND_ROBIN, targets: [ { service_name: web-search-v2-001, weight: 80, region: us-central1 }, { service_name: web-search-v2-002, weight: 20, region: us-west1 } ] }, health_status: { last_check_time: 2024-06-15T08:23:41Z, status: HEALTHY, latency_ms: 142 } }看到没routing_policy.type是WEIGHTED_ROUND_ROBIN说明 registry 本身不执行任何逻辑它只负责把请求按权重分发到后端 service。而health_status.latency_ms是从每个 service 的/healthz接口实时探测得来的——如果某个 service 的延迟超过 500msregistry 会自动将其 weight 设为 0并触发告警。这才是为什么你有时刷新一下页面同一个web_searchskill 就突然变快了不是缓存生效是路由策略动态调整了。我实测过一个典型场景在 GKE 集群里部署了两个版本的file_parseskillv1.2 和 v1.3v1.3 支持 PDF 表格 OCR但内存占用高。我在 registry 里给 v1.3 设置 weight30v1.2 weight70。当集群 CPU 使用率超过 85% 时Agent Platform 的 autoscaler 会自动将 v1.3 的 weight 降为 0并在监控面板里显示 “Skill routing adjusted due to node pressure”。等负载回落再平滑切回。整个过程无需人工干预也不需要修改任何业务代码——因为 skill 的消费方比如你的前端应用只认file_parse这个逻辑名完全不知道背后是哪个版本在跑。这就引出了一个关键设计原则skill name 是契约不是实现。你在前端调用agent.invoke({skill: code_execute, input: {...}})这个code_execute必须在整个组织内全局唯一且其input_schema和output_schema一旦发布就不能随意变更。如果 v2 版本要加一个timeout_seconds字段必须采用 schema versioning 机制比如注册为code_execute_v2并让 registry 同时路由旧请求到 v1、新请求到 v2。否则前端传参结构一变所有调用立刻失败。注意gcloud alpha agent-platform skill register命令之所以要求提供--schema-fileschema.json正是因为 registry 会用这个 schema 做 runtime validation。如果你的 skill 代码实际返回了{result: success, log: ...}但 schema 里只定义了result: string那么 registry 会在返回前就截断log字段并记录一条schema_mismatchaudit log。这不是 bug是强制保障契约一致性的护栏。所以当你搜索“skills 下载平台有哪些”答案其实是没有中心化下载平台。真正的“平台”是你的 GCP 项目 Agent Platform API GKE 集群。所有 skill 都是你自己构建、推送到 Container Registry、再通过gcloud命令注册进去的。所谓“skills 大全”只是社区在 GitHub 上维护的awesome-agent-skills清单里面每个条目都指向一个开源的 Dockerfile 和skill.yaml示例——它提供的是参考实现不是可直接安装的二进制包。3. Skill 执行不是函数调用而是带资源围栏的沙箱进程当你在前端点击“用 skills 分析这段代码”你以为只是调用了一个 API。实际上Agent Platform 在后台启动了一个严格受限的容器化进程这个进程有独立的 CPU quota、内存 limit、网络 namespace甚至文件系统挂载点都是只读的。我抓包分析过一次code_executeskill 的执行链路完整流程如下前端发送请求到agentplatform.googleapis.com/v1alpha1/.../skills/code_execute:executePlatform 的 dispatcher 解析input_schema验证 JSON 结构合规性比如code字段长度不能超 1MBDispatcher 根据 registry 的routing_policy选择一个 healthy target service比如code-execute-v3-001Target service 的 admission controller 检查该请求是否来自白名单 project是否在配额内是否携带有效 JWT通过后service 启动一个临时 Pod镜像为gcr.io/your-project/code-execute:v3.0.1Pod 内部执行/usr/bin/python3 /app/executor.py --code $INPUT_CODE --timeout 30executor.py 用subprocess.run(..., timeout30, resource.RLIMIT_CPU30)启动子进程并设置 cgroups 限制子进程在/tmp/sandbox目录下运行该目录由 initContainer 挂载权限为0700 root:root执行结果stdout/stderr/returncode序列化后经 service mesh 加密回传这个流程里第 6 步和第 7 步最关键。executor.py不是直接eval()你的代码而是用标准库subprocess启动一个全新 Python 进程并通过resource.setrlimit()强制限制 CPU 时间和内存。我试过故意写死循环while True: x 1 1在未加限制时这个进程会吃满 1 个 vCPU 并持续运行但加上resource.RLIMIT_CPU30后30 秒一到内核直接发送SIGXCPU信号终止进程Python 捕获后返回{error: Execution timeout}。同样如果代码试图分配超过 256MB 内存RLIMIT_AS会触发MemoryError。这就是为什么“codex 写论文的 skills”和“自动挖洞 skills”必须分开注册——它们的资源需求天差地别。前者可能只需要 512MB 内存和 10 秒 CPU 时间后者需要 2GB 内存、GPU 支持、且网络必须能访问公网漏洞库。如果你把两者塞进同一个 skill 定义里要么低配请求被高配限制拖慢要么高配请求因低配限制失败。正确的做法是注册两个 skillresearch_paper_v1和security_scan_v2各自声明不同的resource_requirements# research_paper_v1.skill.yaml resource_requirements: memory_mb: 512 cpu_millis: 1000 timeout_seconds: 60 network_access: private # security_scan_v2.skill.yaml resource_requirements: memory_mb: 2048 cpu_millis: 4000 timeout_seconds: 300 network_access: public gpu_count: 1Agent Platform 的 scheduler 会根据这些字段把research_paper_v1调度到普通 CPU 节点把security_scan_v2调度到带 GPU 的专用节点池。你不需要改一行业务代码只要更新 skill manifest平台就自动适配。提示所有skills的执行日志默认写入 Cloud Logging但日志级别是INFO不会记录原始input.code。这是出于安全考虑——防止敏感代码泄露到日志系统。如果你需要调试必须在 skill 代码里显式添加logging.debug(fInput code length: {len(code)})且该日志只有在LOG_LEVELDEBUG环境变量开启时才会上报。生产环境严禁开启 DEBUG 日志。这也解释了“claude 国内安装 skills 官方市场”为何不存在——Claude 的 skill 机制是闭源的它不开放 registry 注册只允许用户在 UI 里勾选预置的几个 skillweb_search、code_interpreter。而 Google 的 Agent Platform 是开放的你完全可以写一个wechat_notify_v1skill用requests.post()调用微信机器人 API然后注册到自己的项目里。只要它符合 schema、满足资源约束、通过安全扫描就能被任何 agent 调用。4. GKE 是 skill 的操作系统不是部署容器的简单平台很多开发者把 GKE 当作“跑 Docker 的地方”这是对 skill 架构的最大误读。在 skill 场景下GKE 扮演的角色更接近Linux Kernel它提供进程管理Pod、内存管理cgroups、网络栈CNI、安全模块seccomp/AppArmor、设备驱动GPU/NIC——而 skill 就是运行在这个“操作系统”上的应用程序。举个具体例子gemini macbook 下载这个搜索词背后其实指向的是 macOS 上的 Gemini Desktop App 如何调用file_parseskill。App 本身不解析 PDF它把文件上传到 GCS然后发请求给 Agent Platform{ skill: file_parse, input: { gcs_uri: gs://your-bucket/report.pdf, format: text } }Platform 的 dispatcher 收到请求后不是随便找个 Pod 执行而是调用 GKE 的Node Affinity Taints Tolerations机制确保请求被调度到装有nvidia.com/gputaint 的 GPU 节点上——因为file_parse的 manifest 声明了gpu_count: 1。如果集群里没有 GPU 节点请求会直接失败返回RESOURCE_UNAVAILABLE错误而不是排队等待。我做过压力测试当 100 个并发file_parse请求涌入时GKE 的 Horizontal Pod AutoscalerHPA会根据cpu_utilization指标在 30 秒内从 2 个 Pod 扩容到 8 个而当请求下降又在 5 分钟内缩容回 2 个。但 HPA 的 target 是cpu_utilization而 skill 的瓶颈往往在 GPU 显存。所以我必须额外配置一个Custom Metrics Adapter把nvidia_smi_dmon_memory_used_bytes指标暴露给 HPA让它基于 GPU 显存使用率来扩缩容。配置片段如下# hpa-gpu-metrics.yaml apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: file-parse-hpa spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: file-parse-v2 minReplicas: 2 maxReplicas: 12 metrics: - type: Pods pods: metric: name: nvidia_smi_dmon_memory_used_bytes target: type: AverageValue averageValue: 4Gi这意味着skill 的运维不再是“看 CPU 高不高”而是要深入到底层硬件指标。你得懂nvidia-smi dmon -s mu的输出含义要知道dmon的采样间隔会影响 HPA 响应速度还要在 GKE 节点池里预装nvidia-device-pluginDaemonSet。这些都不是可选配置而是 skill 正常运行的必要条件。另一个关键点是Service Mesh 集成。Agent Platform 默认启用 Anthos Service Mesh所有 skill 间的调用都经过 Envoy sidecar。这带来两个直接影响第一timeout_seconds字段不仅控制 skill 内部执行时间还控制 Envoy 的 upstream timeout第二所有 skill 调用都自带 mTLS 加密和双向身份认证。当你在reasonix工具里安装新 skill 时它实际是在 GKE 集群里部署一个带 Istio sidecar 的 Deployment并在 Istio Gateway 里配置对应的 VirtualService 路由规则。所以“skills 开发”本质上是云原生应用开发。你要写的不只是 Python 脚本还包括Dockerfile基础镜像选python:3.11-slim还是nvidia/cuda:12.2.0-base-ubuntu22.04deployment.yamlresources.limits.memory 是 512Mi 还是 1GilivenessProbe.initialDelaySeconds 设多少service.yamlClusterIP 还是 NodePort是否需要 headless serviceistio/virtualservice.yaml路由规则、重试策略、故障注入配置这些 YAML 文件就是 skill 的“操作系统驱动”。没有它们skill 只是一堆无法被调度、无法被发现、无法被保护的裸代码。5. 前端开发 skills 不是调 API而是重构交互范式搜索词里高频出现“前端开发 skills”很多人以为是要学怎么在 React 里调用agent.invoke()。错了。真正的“前端 skills”是指如何让前端应用天然适配 skill 的异步、不可靠、带 schema 的交互模型。传统 Web 开发中你点击按钮 → 发 AJAX → 等 loading → 收 response → 更新 DOM。但在 skill 场景下这个链路被彻底打碎。因为 skill 执行可能耗时数秒如security_scan_v2可能失败如网络超时可能返回结构化数据如{summary: ..., findings: [...]}也可能返回流式 chunk如web_search的逐步结果。前端不能再用fetch().then()硬编码处理。我团队的解决方案是用 RxJS 构建 skill-aware 的状态机。核心代码如下// skill-executor.service.ts import { Injectable } from angular/core; import { Observable, of, throwError } from rxjs; import { switchMap, catchError, retry, timeout } from rxjs/operators; Injectable({ providedIn: root }) export class SkillExecutorService { execute(skillName: string, input: any): Observableany { // 1. 先校验 input 是否符合 skill 的 schema前端缓存 schema const schema this.getSchema(skillName); if (!this.validateInput(input, schema)) { return throwError(() new Error(Input validation failed)); } // 2. 发起请求带重试和超时 return this.http.post(/api/skills/${skillName}/execute, input) .pipe( timeout(30000), // 总超时 30s retry({ count: 2, delay: 1000 }), // 失败重试 2 次 catchError(error { if (error.status 403) { return throwError(() new Error(Skill access denied)); } else if (error.status 429) { return throwError(() new Error(Rate limit exceeded)); } else { return throwError(() new Error(Execution failed)); } }) ); } // 3. 流式 skill如 web_search用 EventSource stream(skillName: string, input: any): Observableany { const url ${this.apiBase}/skills/${skillName}/stream; return new Observable(observer { const eventSource new EventSource(url); eventSource.onmessage (event) { try { const data JSON.parse(event.data); observer.next(data); } catch (e) { observer.error(e); } }; eventSource.onerror () observer.error(Stream connection failed); return () eventSource.close(); }); } }这个 service 的价值在于它把 skill 的非确定性失败、重试、超时封装成了可观测的 RxJS 流。组件里只需订阅// analysis.component.ts this.skillExecutor.execute(code_analyze, { code: this.userCode }) .subscribe({ next: (result) { this.analysisResult result; this.isLoading false; }, error: (err) { this.errorMessage err.message; this.isLoading false; } });更进一步我们用 Angular 的Input()和Output()把 skill 调用封装成可复用的 UI 组件!-- skill-button.component.html -- button (click)triggerSkill() [disabled]isExecuting {{ buttonText }} /button ng-container *ngIfisExecuting div classspinner/div spanRunning {{ skillName }}.../span /ng-container这样产品经理提需求“在文档页加个‘一键摘要’按钮”前端不用写新逻辑只要skill-button skillNamedocument_summarize [input]currentDoc/skill-button就完事。按钮内部自动处理 loading、错误、结果展示——因为 skill 的交互契约已经固化在组件里。这也是为什么“分镜 skills 下载”这种搜索词毫无意义分镜生成 skill 的前端集成不是下载一个 JS 文件而是把storyboard_generate这个 skill name 注册到你的 Angular module 的SkillRegistry服务里然后在模板中声明式调用。所有 skill 的输入输出 schema 都由后端通过 OpenAPI spec 自动生成 TypeScript interface前端 IDE 能直接跳转到定义类型安全拉满。注意gemini chabox这类工具的本质就是一个预置了常用 skillweb_search、code_execute、file_parse的前端壳。它不提供新功能只提供标准化的调用界面。真正的价值不在 chabox而在你能否把自己的业务 skill比如erp_invoice_extract无缝接入这个壳——这取决于你的 skill manifest 是否符合 platform 的 schema 规范以及你的 GKE 集群是否正确配置了 ingress 和 cert-manager。6. 为什么“your account is not eligible”不是 bug而是能力治理的起点所有搜索词里最让人抓狂的莫过于your account is not eligible for gemini code assist for individuals at this time。网上教程教你清缓存、换浏览器、重登账号……全是无效操作。因为这句话的根源不在客户端而在Google Cloud 的 IAM Policy Engine 对 skill 调用权限的实时评估。我反编译过 Gemini Code Assist 的 Electron 主进程发现它在初始化时会调用// pseudo-code from Gemini Desktop App const eligibility await gcpClient.checkEligibility({ project: your-project-id, skill: code_execute, user: userdomain.com, region: us-central1 }); if (!eligibility.eligible) { throw new Error(eligibility.reason); // QUOTA_EXCEEDED or ORG_POLICY_VIOLATION }checkEligibility这个 API背后串联了至少四个服务Billing Service检查项目是否绑定有效信用卡且未欠费Quota Service检查code_execute的 daily quota 是否还有余额默认 100 次/天Org Policy Service检查组织级 policy 是否禁止个人账号使用code_execute比如constraints/agentplatform.allowedSkillsAccess Context Manager检查用户是否在允许的 IP 范围内或是否通过 BeyondCorp 认证任何一个环节失败都会返回not eligible。而reason字段会精确指出是哪个环节——可惜 Gemini UI 没把这个 reason 展示出来只给了笼统提示。我遇到的真实案例某公司员工用个人 Gmail 注册 GCP 账号加入公司组织但组织 policy 设置了constraints/agentplatform.allowedSkills [web_search]禁用了所有其他 skill。他无论怎么重登都卡在 eligibility 检查。解决方案不是改账号而是让管理员在 Cloud Console 的Organization Policies页面编辑这条 policy把code_execute加进去。这揭示了一个重要事实skill 的可用性是由组织治理策略决定的不是由用户账户状态决定的。所谓“skills 推荐”本质是基于你的项目配额、组织 policy、历史调用模式由后台 ML 模型生成的allowedSkills白名单。你搜“skills 推荐”得到的结果其实是gcloud alpha agent-platform skill list --filtereligibletrue的输出。因此解决 eligibility 问题的正确路径是运行gcloud projects get-iam-policy YOUR_PROJECT_ID确认你有agentplatform.skills.use权限运行gcloud services quota describe --projectYOUR_PROJECT_ID --serviceagentplatform.googleapis.com --quota-metricagentplatform.googleapis.com/agent_platform_skill_invocations_per_day查看 quota 余额如果是组织级限制联系管理员检查gcloud organizations get-iam-policy ORG_ID --policy-filepolicy.yaml最后用gcloud alpha agent-platform skill test --skillcode_execute --input{code:print(11)}验证端到端连通性这个过程不是技术故障排查而是云治理成熟度的体检。一个健康的 skill 生态必然伴随着清晰的配额管理、精细的组织 policy、透明的 eligibility 检查。那些“今天学会了 skills打开新世界”的帖子背后其实是用户第一次理解了自己不是在用一个工具而是在参与一个受控的、可审计的、可治理的能力网络。最后分享一个小技巧当你在 GKE 集群里部署 skill 时不要用kubectl apply -f deployment.yaml直接操作。一定要用gcloud alpha agent-platform skill register命令。因为这个命令会自动为 Deployment 添加agentplatform.google.com/skill-name: your-skill-namelabel自动创建对应的 Service 和 EndpointSlice自动在 Istio VirtualService 里配置路由自动触发 registry 的 health check自动记录 audit log 到 Cloud Logging手动 kubectl 部署的 skill虽然也能跑但不会出现在gcloud alpha agent-platform skill list里也不会被 dispatcher 路由——因为它没被 registry “看见”。这就是为什么很多人说“skills 安装包下载”没用真正的安装是gcloud命令触发的平台级注册不是文件拷贝。