1. 从skills这个词说起为什么它突然成了AI Agent圈子的高频词如果你最近在关注AI Agent相关的技术动态大概率会反复撞见skills这个词。它不是一个新概念但在Agent语境下被重新激活之后含义发生了明显偏移。以前我们说一个AI模型有什么能力通常指的是它在训练阶段习得的泛化本领比如写代码、做翻译、总结长文。而现在说一个Agent具备某项skill更多是指它在运行时可以调用的一段封装好的、有明确输入输出契约的执行单元。这个区别非常关键。前者是模型会什么后者是Agent能做什么。前者靠参数记忆后者靠工程编排。我刚开始接触这个概念的时候也犯过迷糊觉得不就是function calling换了个名字吗后来在实际项目里踩了几次坑才明白skills这套思路解决的是Agent从能聊天到能干活之间的最后一公里问题。这篇文章我想聊的不是某个具体产品的使用教程而是围绕skills这个核心概念把它的设计逻辑、落地方式、常见坑位和排查思路完整拆一遍。适合已经在做Agent应用、或者正准备把LLM接入真实业务流程的开发者看。如果你还在纠结要不要用Agent那这篇可能稍微超前了一点但也可以当作技术选型的参考。核心关键词会自然穿插在下面各个章节里Agent Skills、Google Cloud、AI agents、GKE、Genkit以及最近讨论度很高的agent skills测试和first principles deep dive。我不会堆砌这些词而是把它们放到真实的工程语境里讲。2. Agent Skills到底是什么一次概念层面的彻底拆解2.1 从模型能力到可调用技能的范式转移传统意义上我们评估一个LLM的能力看的是benchmark分数、上下文窗口、推理链长度这些指标。但当你真的要把LLM塞进一个业务系统比如自动处理客服工单、自动生成周报、自动巡检云资源你会发现模型本身的聪明程度只是必要条件远不是充分条件。原因很简单模型不知道你的数据库表结构不知道你的API鉴权方式不知道你的业务规则里退款和退货是两个完全不同的流程。这些知识如果全部塞进prompt上下文会爆炸而且维护成本极高。Agent Skills的思路就是把这些领域知识拆成一个个独立的、可组合的技能单元每个单元负责一件具体的事模型只负责决定什么时候调用哪个技能。我习惯用一个类比来解释模型是大脑skills是手和脚。大脑再聪明没有手脚也干不了活。而skills的设计质量直接决定了这个Agent是能干活还是帮倒忙。2.2 Skill的四个核心要素名称、描述、参数、执行体一个合格的skill不管你在哪个框架里实现本质上都包含四个部分。这四个部分缺一个Agent的调用成功率就会断崖式下跌。名称name必须是动词开头的短标识符比如query_order_status、send_notification。不要用order这种模糊词模型会不知道你要它干什么。描述description这是最容易被低估的部分。描述不是给人看的是给模型看的。它决定了模型在什么场景下会选中这个skill。我见过太多项目把描述写成查询订单结果模型在用户问我的包裹到哪了的时候完全不触发。正确的写法应该包含触发场景、输入语义、输出语义甚至反例。参数parameters用JSON Schema定义每个字段都要有类型、必填标记和描述。参数描述同样要写给模型看比如order_id的描述应该是用户提供的订单编号通常是12位数字而不是订单ID。执行体executor真正干活的代码可以是一个HTTP请求、一段数据库查询、一次云函数调用。执行体要处理好超时、重试和错误返回因为模型拿到错误信息之后往往会尝试修复如果错误信息不清晰它会陷入死循环。2.3 为什么Google Cloud和Genkit在这个话题里频繁出现Agent Skills本身是一个抽象概念但落地需要具体的运行时。Google Cloud在这方面的布局比较完整GKE负责承载Agent服务的容器化部署Genkit负责技能的定义、编排和可观测性Vertex AI负责模型侧的能力供给。这三者组合起来基本覆盖了从开发到上线的全链路。Genkit特别值得说一下。它提供了一套声明式的skill定义方式你可以用TypeScript或Go写skill然后通过统一的接口暴露给模型。它的flow机制可以把多个skill串成一条执行链中间还带状态管理和错误恢复。我在一个内部项目里用Genkit做过工单自动分类的Agent从定义skill到跑通端到端流程大概花了两个下午这个效率在以前用裸写function calling的方式下是不可想象的。GKE的角色则更偏基础设施。Agent服务通常需要弹性伸缩因为调用量波动很大白天可能每分钟几百次凌晨可能一次都没有。GKE的HPA配合自定义指标可以根据队列长度或者并发请求数来扩缩容比固定副本数经济得多。而且GKE的Workload Identity可以让Agent服务安全地访问其他云资源不用把密钥硬编码在环境变量里。3. 设计一个靠谱的Skill从需求到落地的完整思路3.1 先想清楚谁来调用再动手写代码这是我最想强调的一点。很多开发者拿到需求就开始写skill的执行逻辑写完发现模型根本不会调用或者调用了但参数传错。根本原因是他们在设计阶段没有站在模型的角度思考。模型调用skill的决策过程本质上是一个语义匹配问题。它看到用户输入然后在所有可用skill的描述里找最匹配的那个。所以你的skill描述必须和用户的自然语言表达方式对齐。比如用户说帮我看看上周的账单你的skill描述里如果只有查询账单明细匹配度就不够高。更好的描述是查询指定时间范围内的账单明细支持按周、按月、按自定义区间查询。我的做法是在写skill之前先收集20到50条真实的用户输入样本然后人工标注每条应该触发哪个skill。这个过程能帮你发现很多边界情况比如有些输入其实不应该触发任何skill而是应该直接由模型回答。这些负样本同样重要它们能帮你调整skill描述的排他性。3.2 参数设计宁可多一个可选字段不要少一个必填字段参数设计有个反直觉的原则必填字段越少越好。因为模型在提取参数的时候如果某个必填字段在用户输入里找不到它要么会编造一个值要么会反复追问用户。前者导致错误执行后者导致体验糟糕。我通常会把参数分成三档核心必填、上下文推断、可选补充。核心必填是那些没有就完全没法执行的比如查询订单必须要有订单号。上下文推断是那些可以从对话历史或者系统状态里拿到的比如用户ID、当前时间。可选补充是那些有更好、没有也能跑的比如分页大小、排序方式。这里有个实操技巧对于上下文推断类的参数不要让模型去提取而是在执行体里自动注入。比如用户ID完全可以从会话上下文里拿没必要让模型每次都问一遍。这样既减少了模型的负担也避免了隐私信息在prompt里反复出现。3.3 错误处理模型不是异常处理器我见过最离谱的一个案例是某个skill在执行失败时返回了一段500字的堆栈信息结果模型把这段堆栈当成了业务数据继续往下处理最后生成了一个完全错误的回复。模型不是异常处理器它不理解技术错误。所以skill的错误返回必须是结构化的、语义化的。我的做法是定义一套错误码和对应的自然语言说明比如ORDER_NOT_FOUND对应未找到该订单请确认订单号是否正确PERMISSION_DENIED对应当前用户无权查看该订单。模型拿到这些信息之后可以决定是重试、换一个skill还是直接告诉用户。另外超时设置也很关键。Agent场景下用户对响应时间的容忍度通常在5秒以内。如果一个skill的执行时间可能超过3秒就应该考虑异步化先返回一个处理中的状态然后通过轮询或者推送来获取结果。GKE上的Agent服务可以配合Cloud Tasks做异步任务编排这个组合我在生产环境里用过稳定性不错。4. 实操用Genkit定义一个可测试的Agent Skill4.1 环境准备与依赖安装先说一下前置条件。你需要一个Google Cloud项目启用了Vertex AI API和Cloud Run或者GKE。本地开发的话Node.js 18以上npm或者pnpm都行。我习惯用pnpm速度快一些。npm install -g genkit-cli pnpm init pnpm add genkit genkit-ai/googleai genkit-ai/vertexai zodGenkit的核心包是genkit模型接入用genkit-ai/vertexai或者genkit-ai/googleai参数校验用zod。如果你打算部署到GKE还需要Docker和kubectl这个后面再说。4.2 定义一个查询订单状态的Skill下面是一个完整的skill定义示例。我特意把描述写得比较详细因为这是决定调用成功率的关键。import { genkit, z } from genkit; import { vertexAI } from genkit-ai/vertexai; const ai genkit({ plugins: [vertexAI({ location: us-central1 })], model: vertexai/gemini-1.5-pro, }); export const queryOrderStatus ai.defineTool( { name: queryOrderStatus, description: 查询指定订单的当前状态和物流信息。 适用场景用户询问订单进度、包裹位置、预计送达时间。 不适用场景用户询问退款进度请使用queryRefundStatus、 用户询问商品库存请使用queryInventory。 输入需要订单号订单号通常是12位数字以ORD开头。, inputSchema: z.object({ orderId: z.string().describe(订单编号格式为ORD开头加12位数字), includeLogistics: z.boolean().optional().describe(是否包含物流轨迹默认false), }), outputSchema: z.object({ status: z.string(), estimatedDelivery: z.string().optional(), logistics: z.array(z.object({ time: z.string(), location: z.string(), description: z.string(), })).optional(), }), }, async (input) { // 实际项目中这里调用你的订单服务API const response await fetch(${process.env.ORDER_SERVICE_URL}/orders/${input.orderId}); if (!response.ok) { if (response.status 404) { throw new Error(ORDER_NOT_FOUND: 未找到该订单请确认订单号是否正确); } throw new Error(ORDER_SERVICE_ERROR: 订单服务暂时不可用请稍后重试); } return await response.json(); } );这段代码有几个细节值得展开。第一描述里明确写了适用和不适用场景这能显著降低误触发的概率。第二orderId的描述里给了格式提示模型在提取参数时会更有针对性。第三错误信息是语义化的模型能理解并转述给用户。4.3 把多个Skill串成一条Flow单个skill只能干一件事真正的业务场景往往需要多个skill协作。Genkit的flow机制就是干这个的。export const orderInquiryFlow ai.defineFlow( { name: orderInquiryFlow, inputSchema: z.object({ userQuery: z.string() }), outputSchema: z.string(), }, async (input) { const response await ai.generate({ prompt: input.userQuery, tools: [queryOrderStatus, queryRefundStatus, queryInventory], system: 你是一个电商客服助手。根据用户问题选择合适的工具。 如果用户问题涉及多个方面可以依次调用多个工具。 如果工具返回错误向用户解释原因并给出建议。, }); return response.text; } );这个flow把三个skill注册给模型由模型自主决定调用顺序。实测下来Gemini 1.5 Pro在多工具选择上的准确率相当不错但前提是每个skill的描述足够清晰、边界足够明确。4.4 本地测试与agent skills测试方法Genkit自带一个开发者UI运行genkit start之后会打开一个本地页面你可以在里面直接输入用户query看模型选择了哪个skill、传了什么参数、返回了什么结果。这个UI在调试阶段非常有用比看日志直观得多。但光靠手动测试不够。我建议写一套自动化的agent skills测试用例覆盖三类场景正常调用、边界调用、错误处理。正常调用就是标准的用户输入边界调用包括模糊表达、多意图混合、参数缺失错误处理包括服务不可用、权限不足、数据不存在。const testCases [ { input: 我的订单ORD123456789012到哪了, expectedTool: queryOrderStatus }, { input: 帮我查下退款进度, expectedTool: queryRefundStatus }, { input: 这个订单能退吗顺便看看物流, expectedTool: [queryOrderStatus, queryRefundStatus] }, { input: 今天天气怎么样, expectedTool: null }, ];这套测试跑下来基本能暴露80%以上的skill设计问题。我自己的经验是描述写得再仔细也总会有意想不到的输入方式所以测试用例要持续补充最好把线上真实的失败case也加进去。5. 部署到GKE让Agent服务扛住真实流量5.1 容器化与资源配置Agent服务本质上就是一个HTTP服务容器化没什么特别的。但有几个资源配置需要特别注意。FROM node:18-slim WORKDIR /app COPY package.json pnpm-lock.yaml ./ RUN npm install -g pnpm pnpm install --frozen-lockfile COPY . . RUN pnpm build EXPOSE 8080 CMD [node, dist/server.js]资源请求和限制方面我的经验是CPU request给500mlimit给2000m内存request给512Milimit给2Gi。Agent服务的CPU消耗主要在模型调用和JSON解析上内存消耗主要在上下文管理上。如果并发量高内存限制给大一点避免OOM。5.2 自动扩缩容策略GKE的HPA默认基于CPU和内存但Agent服务更适合基于并发请求数或者队列长度来扩缩容。你可以通过Custom Metrics Adapter把应用层的指标暴露给HPA。apiVersion: autoscaling/v2 kind: HorizontalPodAutoscaler metadata: name: agent-service-hpa spec: scaleTargetRef: apiVersion: apps/v1 kind: Deployment name: agent-service minReplicas: 2 maxReplicas: 20 metrics: - type: Pods pods: metric: name: concurrent_requests target: type: AverageValue averageValue: 10这个配置的意思是每个Pod平均处理10个并发请求时触发扩容。minReplicas设为2是为了保证高可用maxReplicas设为20是根据预算和下游服务承载能力定的。实际数值需要压测之后调整。5.3 可观测性日志、指标、追踪一个都不能少Agent服务的排查难度比普通服务高因为它的行为有不确定性。同一个输入模型可能选择不同的skill或者传不同的参数。所以可观测性必须做扎实。日志方面每次skill调用都要记录用户输入、模型选择的skill、传入的参数、执行结果、耗时。这些日志用结构化格式输出方便后续分析。指标方面重点监控skill调用成功率、平均耗时、模型token消耗量。追踪方面Genkit内置了OpenTelemetry支持可以把一次完整的flow执行串成一条trace每个skill调用是一个span。我在生产环境里遇到过一个诡异的问题某个skill的调用成功率突然从98%掉到70%但错误日志里没有任何异常。后来通过trace发现是模型开始把某个参数传成字符串null而不是真正的null导致执行体里的类型判断失败。这种问题没有trace根本查不出来。6. 常见问题与排查技巧实录6.1 模型不调用Skill或者调用错误的Skill这是最高频的问题。排查顺序应该是先看skill描述是否清晰再看参数schema是否有歧义最后看system prompt是否给了足够的引导。一个常见的误区是skill数量太多。我建议单个Agent的skill数量控制在10个以内超过之后模型的選擇准确率会明显下降。如果业务确实需要更多skill可以考虑分层先让模型选择一个skill类别再在类别内选择具体skill。另一个技巧是在描述里加入反例。比如queryOrderStatus的描述里明确写不适用于退款查询这能有效减少误触发。6.2 参数提取失败或者提取错误参数提取失败通常有两个原因一是参数描述不够具体二是用户输入里确实没有这个信息。前者靠优化描述解决后者靠设计合理的追问话术。我习惯在skill的inputSchema里给每个字段加describe而且描述要包含格式示例。比如日期字段描述写成日期格式为YYYY-MM-DD例如2024-01-15比只写日期效果好得多。如果某个参数经常提取失败可以考虑把它改成可选然后在执行体里做默认值处理。比如分页大小默认给20模型提取不到就用默认值没必要让它反复追问。6.3 Skill执行超时或者下游服务不稳定Agent场景下下游服务不稳定是常态。我的做法是在skill执行体里加三层保护超时控制、重试策略、熔断降级。超时控制用AbortController实现一般设3秒。重试策略用指数退避最多重试2次。熔断降级可以用简单的计数器实现连续失败5次之后直接返回降级结果避免雪崩。async function withRetryT(fn: () PromiseT, maxRetries 2): PromiseT { for (let i 0; i maxRetries; i) { try { const controller new AbortController(); const timeout setTimeout(() controller.abort(), 3000); const result await fn(); clearTimeout(timeout); return result; } catch (err) { if (i maxRetries) throw err; await new Promise(r setTimeout(r, Math.pow(2, i) * 200)); } } throw new Error(UNREACHABLE); }6.4 常见问题速查表问题现象可能原因排查方法解决方案模型不调用任何skillskill描述与用户表达不匹配查看trace中模型的决策日志优化描述加入同义表达调用了错误的skillskill之间边界模糊检查各skill描述的排他性加入反例说明减少skill数量参数提取为空参数描述不具体查看模型输出的参数JSON补充格式示例改为可选执行超时下游服务响应慢查看skill执行耗时指标加超时控制异步化处理错误信息被模型误解错误返回非结构化检查错误返回格式改用语义化错误码并发高时成功率下降资源不足或下游限流查看HPA指标和下游QPS扩容加限流和降级7. 一些踩坑之后的个人体会Agent Skills这套东西概念不复杂但落地细节极多。我最大的体会是skill的设计质量比模型的选择能力更重要。同一个模型用设计良好的skill和设计粗糙的skill效果差距可能是天壤之别。另一个体会是测试要趁早、要自动化。Agent的行为有不确定性手动测试覆盖不了多少场景。我现在的习惯是每加一个skill就同步加至少5条测试用例跑通了再上线。这套流程虽然前期麻烦但后期省下的排查时间远超投入。最后说一个容易被忽略的点skill的版本管理。skill的描述和参数schema一旦上线就不要随意改动因为模型的行为会跟着变。如果必须改要做好灰度发布和回滚准备。我吃过这个亏改了一个skill的描述之后另一个不相关的skill调用率突然飙升查了半天才发现是描述里的某个词产生了语义干扰。这个领域还在快速演进Genkit和GKE的能力也在持续更新。保持关注但不要盲目追新把手上的一套流程跑稳比什么都重要。