1. 从skills这个标题说起一个被低估的工程概念第一次看到skills这个标题很多人会下意识觉得它太泛了——技能什么技能是个人能力清单还是某个框架里的功能模块但如果把最近围绕 Agent Skills、Google Cloud、GKE、Genkit、BigQuery 这一串热词放在一起看方向其实就清晰了这里说的 skills指的是智能体Agent可调用的能力单元是把一个通用大模型变成能干活的专业助手的那一层封装。我在实际项目里踩过最典型的一个坑就是一开始把 skills 理解成提示词模板。写了几十个 prompt每个都挺精致结果一上生产就崩模型不知道该在什么时候调用哪个模板参数对不上返回结果没法结构化解析多个 skill 之间还会互相打架。后来才想明白skills 的本质不是话术而是带契约的能力接口——它有明确的输入、明确的输出、明确的触发条件以及明确的失败处理方式。这个认知转变是整篇内容想跟你聊透的核心。这篇内容适合三类人看一是正在做 Agent 应用、被模型不听话折磨的开发者二是想把内部工具、数据、流程接进智能体但不知道从哪下手的工程团队三是已经用过 Genkit、GKE、BigQuery 这些组件想把它们串成一个完整 skills 体系的人。我会从概念拆解讲到落地实操包括 skill 的契约设计、在 Google Cloud 上的部署形态、用 Genkit 编排、用 BigQuery 做数据支撑以及我自己踩过的那些坑。不堆概念尽量说人话能抄的配置和步骤我都会给出来。2. Agent Skills 到底是什么把能力从模型里拆出来2.1 为什么不能把所有逻辑都塞进一个 prompt先说一个反直觉的结论skills 存在的意义恰恰是为了让模型少知道一点东西。听起来很怪但这是我在做了几个 Agent 项目之后最深的体会。如果你把所有能力——查数据库、发邮件、算价格、调外部 API——全部写进一个巨大的系统提示词里会发生什么模型每次推理都要读完这一大坨token 成本飙升不说更致命的是注意力被稀释。它会在我该查数据库还是该直接回答之间反复摇摆输出不稳定。我实测过一个场景把 8 个能力塞进单个 prompt任务成功率大概在 60% 上下浮动拆成 8 个独立 skill 之后同样的模型、同样的任务成功率稳定在 90% 以上。差别不在模型在于决策空间被收敛了。所以 skills 的第一层价值是解耦把什么时候做什么的决策从怎么做的实现里剥离出来。模型只负责判断当前该调用哪个 skill具体怎么执行由 skill 自己负责。这就像公司里的分工——老板不需要知道财务怎么报税只需要知道这事找财务。2.2 skill 的三要素触发、契约、执行一个合格的 skill我习惯用三个要素去检查它是否完整触发条件When什么情况下该用这个 skill。这通常体现在 skill 的 name 和 description 里模型靠这两项做路由决策。description 写得好不好直接决定 skill 会不会被误触发或漏触发。契约Contract输入参数和输出结构的定义。输入要有类型、必填项、取值范围输出要结构化最好能被程序直接解析而不是一段自由文本。执行体How真正干活的代码。可以是一次数据库查询、一次 API 调用、一段计算逻辑甚至是对另一个模型的调用。这三者缺一不可。我见过太多半成品 skill——只有执行体没有清晰的触发描述结果模型根本不知道什么时候该用它或者有触发描述但输出是一段散文下游程序没法用等于白做。2.3 skills 和 tools、functions 的区别在哪这里必须澄清一个容易混淆的点。很多人把 skills 和 tools或 function calling当成一回事其实有细微但重要的差别。function calling 更偏向单次调用的机制模型输出一个函数名和参数你执行完把结果喂回去。它解决的是模型能不能调外部函数的问题。而 skills 更偏向能力的组织形态它可能包含多个函数、多个步骤、甚至内部的状态管理。一个 skill 内部可以调用好几个 tool也可以有自己的重试逻辑和降级策略。打个比方function calling 是打电话这个动作skills 是客服部门这个组织。你可以只打电话但要让整个服务体系跑起来你需要的是组织不是单个动作。在 Genkit 这类框架里这种组织能力体现得尤其明显——它让你把多个步骤编排成一个 flow而每个 flow 对外暴露就是一个 skill。3. 设计一个不会翻车的 skill契约先行3.1 从模型视角写 description而不是从人类视角这是我最想强调的一条经验。写 skill 的 description 时你的读者不是人是模型。人类看查询用户订单能秒懂但模型需要更精确的边界信息。我一般的写法是包含三部分做什么 什么时候用 什么时候不用。举个例子name: query_order_status description: 根据订单号查询订单的当前状态和物流信息。 当用户询问我的订单到哪了订单状态发货了吗这类问题时使用。 不要用于查询历史订单列表用 list_user_orders 也不要用于修改订单用 update_order。注意最后那句不要用于。负向描述往往比正向描述更能提升路由准确率。因为模型在多个 skill 之间做选择时最容易犯的错就是用错相近的 skill明确告诉它边界在哪能显著减少误触发。我实测加一句负向描述误触发率能降三成左右。3.2 输入参数宁可多一个可选不要少一个必填参数设计上有个反直觉的原则必填项越少越好。每多一个必填参数就多一个模型填错或漏填的机会。我的做法是只把没有它就无法执行的参数设为必填其余全部给默认值或设为可选。比如查询订单订单号必填但是否包含物流详情可以默认 true返回条数可以默认 10。这样模型只需要专注填对那一个关键参数成功率自然高。另外参数的类型和格式约束要写清楚。如果订单号是纯数字就在 schema 里约束成数字类型如果是特定格式的字符串就在 description 里给个例子。模型对例子的敏感度远高于对规则的敏感度。3.3 输出结构让下游程序能直接吃输出这块我的血泪教训是永远不要让 skill 返回一段自由文本。哪怕内容再简单也要包成结构化对象。原因很简单自由文本没法被程序可靠解析。你可能会说我用正则提取不就行了但模型每次措辞都可能不一样正则迟早会崩。正确的做法是在 skill 的 schema 里定义好输出字段让模型按结构填充。一个订单查询 skill 的输出大概长这样{ order_id: 12345678, status: shipped, status_text: 已发货, logistics: [ {time: 2024-01-01 10:00, desc: 已揽收} ], estimated_arrival: 2024-01-03 }这样下游无论是展示给用户还是做进一步判断都有稳定的字段可用。结构化输出是 skill 可组合的前提——只有输出规整一个 skill 的结果才能喂给下一个 skill。3.4 失败也要有契约新手最容易忽略的一点skill 的失败路径也要设计。模型调用一个 skill结果它抛异常了这时候模型该怎么办我的做法是让 skill 永远返回一个结构化的结果里面包含 success 字段和 error 字段。执行成功就 successtrue失败就 successfalse 加上错误原因。这样模型拿到结果后能自己决定是重试、换 skill还是告诉用户暂时查不到。如果直接抛异常整个 Agent 流程可能就断了。而返回结构化错误Agent 还有回旋余地。这个设计在 GKE 上跑长流程任务时尤其重要——网络抖动、下游超时都是常态没有失败契约的 skill 会让整个系统变得脆弱。4. 在 Google Cloud 上把 skills 跑起来GKE 与 Genkit 的分工4.1 为什么选 GKE 承载 skill 的执行体skill 的执行体本质上是服务服务就需要运行环境。为什么很多团队选 GKEGoogle Kubernetes Engine来跑我的理解是三个字可控性。Serverless 方案比如纯 Cloud Functions上手快但一旦 skill 变多、调用链变长你会遇到冷启动、并发限制、依赖管理这些麻烦。而 GKE 给你的是完整的容器编排能力你可以给不同的 skill 分配不同的资源配额可以控制副本数应对流量波动可以做灰度发布。对于 skill 数量上双位数、调用量稳定的场景GKE 的性价比和可控性明显更好。具体部署上我一般把一组相关的 skill 打成一个镜像通过 Deployment 部署再用 Service 暴露内部调用入口。每个 skill 对应一个路由Genkit 那边通过 HTTP 调用过来。这样 skill 的升级和 Genkit 的编排逻辑解耦互不影响。4.2 Genkit 在中间层干了什么Genkit 的角色是编排层。它不负责 skill 的具体实现而是负责把 skill 组织成 flow。举个实际例子用户问我上周买的那个东西到哪了。这个请求需要先解析出上周买的对应哪个订单可能要查 BigQuery再调用订单查询 skill最后组织语言回复。这一串步骤在 Genkit 里就是一个 flowflow 内部的每一步可以是一个 skill 调用也可以是一段模型推理。Genkit 的好处是它把模型调用 工具调用 流程控制统一在一套抽象里。你定义 flow 的时候不用关心底层是调模型还是调 API写起来很顺。而且它天然支持流式输出对于需要边想边说的场景很友好。我踩过的一个坑是不要把业务逻辑写进 Genkit 的 flow 里。flow 应该只做编排真正的业务规则放在 skill 内部。否则 flow 会越来越臃肿最后变成一个难以维护的上帝函数。保持 flow 薄、skill 厚是我总结出来的一条铁律。4.3 部署形态对比几种常见组合方案skill 执行体编排层适用场景我的评价全 ServerlessCloud FunctionsGenkit 本地/Cloud Run原型验证、低频调用上手快规模化后成本难控GKE GenkitGKE DeploymentGenkit on Cloud Run中大型生产系统可控性和弹性平衡最好全 GKEGKE DeploymentGenkit on GKE高并发、强隔离需求运维复杂度高但最灵活混合核心 skill 上 GKE边缘 skill 上 FunctionsGenkit成本敏感型需要统一监控否则容易失控这张表是我根据几个项目经验总结的不是标准答案。选哪个取决于你的调用量、团队运维能力和预算。我的建议是从简单方案起步但一开始就把 skill 的接口设计成可迁移的——只要契约稳定执行体从 Functions 迁到 GKE 只是换个部署方式业务代码不用动。5. 用 BigQuery 给 skills 装上记忆和数据底座5.1 什么数据该放 BigQuery什么不该BigQuery 在 skills 体系里的定位是大规模数据查询和分析。但不是所有数据都适合放进去。适合的订单历史、用户行为日志、产品目录、统计报表这类量大、读多写少、需要聚合分析的数据。一个 skill 要查某用户过去一年的消费总额这种聚合查询正是 BigQuery 的强项。不适合的需要频繁单条更新的状态数据比如购物车、对延迟极度敏感的会话数据。这些用传统数据库或缓存更合适。我见过一个反模式把所有数据都往 BigQuery 塞结果一个简单的查用户当前状态也要走 BigQuery延迟高得离谱。BigQuery 是数据仓库不是事务数据库这个边界要守住。5.2 让 skill 安全地查 BigQueryskill 查 BigQuery 有两个必须注意的点参数化查询和权限最小化。参数化查询是为了防注入。永远不要把模型生成的字符串直接拼进 SQL。正确做法是用 BigQuery 的参数绑定from google.cloud import bigquery client bigquery.Client() query SELECT order_id, status, created_at FROM project.dataset.orders WHERE user_id user_id AND created_at start_date ORDER BY created_at DESC LIMIT limit job_config bigquery.QueryJobConfig( query_parameters[ bigquery.ScalarQueryParameter(user_id, STRING, user_id), bigquery.ScalarQueryParameter(start_date, DATE, start_date), bigquery.ScalarQueryParameter(limit, INT64, limit), ] ) results client.query(query, job_configjob_config).result()权限最小化是指跑 skill 的服务账号只给它需要的表的读权限不要给整个数据集的写权限。这样即使 skill 被恶意利用损失也可控。5.3 查询成本控制别让一个 skill 烧掉一个月预算BigQuery 按扫描数据量计费一个写得不小心的 skill 可能一次查询就扫掉几个 TB。我踩过这个坑一个没加分区过滤的查询单次跑了 2TB账单出来的时候心都在滴血。控制成本的手段有几个强制分区过滤在表上设置分区查询时必须带分区条件。BigQuery 支持强制要求分区过滤不开这个选项的表我建议直接不建。限制返回行数skill 的查询永远带 LIMIT避免全表扫描。用物化视图对于高频的聚合查询预先算好存成物化视图skill 直接查视图成本大幅下降。设置自定义配额给项目设置每日查询量上限超过就报警或阻断防止意外。这些措施加起来能把 BigQuery 的成本压到可控范围。成本控制不是优化项是 skill 设计的一部分——一个会烧钱的 skill功能再好也不能上生产。6. 那些让我熬夜的坑skill 实战排错记录6.1 skill 被雪藏模型死活不调用最让人抓狂的问题明明写了 skill模型就是不用自己硬答。我排查了整整一个下午最后发现是 description 写得太谦虚了。原来的 description 是提供订单查询功能。模型看到这句话觉得这好像不是必须的于是选择自己编答案。改成当用户询问订单状态、物流进度时必须调用此 skill 获取准确信息之后调用率立刻上来了。关键词是必须。模型对必须务必一定要这类词的敏感度很高。如果你的 skill 是获取事实性信息的description 里一定要强调必须调用否则模型会倾向于用自己的知识回答而它的知识往往是过时的或编造的。6.2 参数对不上模型填了个看起来对的值第二个坑是参数格式。有个 skill 需要日期参数我在 schema 里写的是 string 类型description 里说格式为 YYYY-MM-DD。结果模型有时候填2024年1月1日有时候填昨天有时候填2024-01-01。下游解析直接崩。解决办法是在 schema 层面约束而不是靠 description 提醒。如果框架支持正则约束就加上正则如果不支持就在 skill 入口做一层参数规范化把各种格式统一转换。永远不要相信模型会严格遵守格式约定它只会尽量遵守。6.3 多 skill 打架相近能力互相抢活当你有两个功能相近的 skill 时模型会在它们之间反复横跳。我遇到过查询订单和查询物流两个 skill用户问我的包裹呢模型有时候调前者有时候调后者结果不稳定。解决思路是合并或明确分层。如果两个 skill 的数据源和逻辑高度重合就合并成一个用参数区分如果确实要分开就在 description 里写清楚各自的适用边界并且让它们的输出结构保持一致这样即使调错了下游也能兼容。我现在的习惯是skill 数量控制在个位数到十几个之间超过这个量就要考虑分组或分层。skill 太多模型的路由准确率会明显下降这是有实测数据支撑的。6.4 超时与重试长流程任务的稳定性在 GKE 上跑 skill网络调用超时是家常便饭。我一开始没做重试结果一个下游 API 抖动整个 flow 就失败了。后来加上了分级重试策略对于幂等的查询类 skill失败后自动重试 2 次间隔递增对于有副作用的操作类 skill比如下单不自动重试而是返回失败让上层决定。这个区分很重要——盲目重试有副作用的操作可能造成重复下单这类严重问题。同时给每个 skill 设置了合理的超时时间。查询类 5 秒复杂分析类 30 秒超过就返回超时错误。超时时间不能设太长否则会拖垮整个 flow 的响应。7. 从能跑到好用skill 体系的持续打磨7.1 给 skill 加可观测性skill 上线只是开始能不能持续优化取决于你有没有数据。我一般会给每个 skill 记录几个关键指标调用次数、成功率、平均耗时、参数分布、失败原因分布。这些数据可以打到 Cloud Logging再用 BigQuery 做聚合分析。有意思的是参数分布往往能暴露设计问题。比如某个 skill 的某个参数90% 的调用都是默认值那说明这个参数可能根本没必要暴露给模型直接写死更省事。失败原因分布则能告诉你该优化哪里。如果大量失败是参数格式错误那就要去改 schema如果是下游超时那就要去优化执行体或加缓存。7.2 用真实对话反哺 skill 设计我有个习惯定期把线上真实的用户对话捞出来看模型在哪些地方犹豫、哪些地方调错 skill、哪些地方该调没调。这些失败样本是最宝贵的设计输入。有一次我发现用户经常问帮我看看最近有没有异常订单而我的 skill 里只有查询指定订单没有查询异常订单。模型只能先查一堆订单再自己判断效果很差。于是我加了一个专门的异常订单 skill问题迎刃而解。skill 的边界不是拍脑袋定的是从真实使用中长出来的。闭门造车设计出来的 skill 体系往往和实际需求有偏差。7.3 版本管理与灰度skill 的契约一旦对外暴露就不能随便改。改参数名、改输出结构都会影响依赖它的 flow。所以我的做法是给 skill 加版本号新版本用新名字老版本保留一段时间等所有调用方迁移完再下线。灰度发布也很重要。新版本 skill 先放 10% 流量观察成功率和耗时没问题再逐步放量。GKE 的滚动更新配合流量切分做这件事很顺手。7.4 一个容易被忽略的点skill 的文档最后说个不起眼但很重要的给 skill 写文档而且是给人看的文档。模型靠 description 路由但维护 skill 的是人。一个新人接手你的 skill 体系如果每个 skill 只有一句 description他会很痛苦。我的文档模板包含skill 用途、输入输出示例、依赖的下游服务、常见失败场景、负责人。花十分钟写文档能省下未来几小时的沟通成本。这笔账怎么算都划算。8. 我个人的一些体会做 Agent Skills 这套东西最大的感受是它考验的不是模型能力而是工程能力。模型再强如果 skill 的契约设计得乱七八糟整个系统照样跑不起来。反过来即使模型一般只要 skill 边界清晰、契约稳定、失败可控系统也能稳定运行。我见过太多团队把精力全花在调 prompt上却忽略了 skill 的接口设计、错误处理、成本控制这些不性感的部分。结果 demo 很惊艳一上生产就原形毕露。Agent 应用的护城河不在模型在 skills 的工程质量。如果让我给刚入门的团队一条建议那就是先把一个 skill 做到极致。从触发描述到契约设计从执行体到失败处理从监控到文档完整地走一遍。这一个 skill 跑通了剩下的就是复制和组合。贪多嚼不烂在 skill 这件事上尤其成立。最后分享一个小技巧每次设计新 skill 之前先问自己一句如果我是模型我看到这个 description 会怎么理解。站在模型的视角审视一遍很多设计问题在写代码之前就能发现。这个习惯帮我省下了大量返工时间。