1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区、开发者群聊还是在做AI应用的朋友圈子里“skills”这个词出现的频率高得离谱。有人把它翻译成“技能包”有人叫它“能力插件”还有人直接管它叫“AI的手和脚”。如果你只是偶尔刷到可能会觉得这又是一个新造的概念过两个月就凉了。但如果你真正动手搭过Agent、跑过工作流、接过外部工具就会发现这个词背后代表的是一整套正在快速成型的工程范式。我最早接触这个概念是在做一个自动化内容处理流程的时候。当时的需求很简单让模型读完一份长文档自动提取关键信息然后调用几个外部接口把结果写进数据库。听起来不复杂但真做起来就发现模型本身只会“说”不会“做”。你得给它配一套工具告诉它什么时候该调用什么、参数怎么传、返回结果怎么解析。这套东西就是现在大家说的skills。所以skills本质上是一种结构化的能力封装。它把一个具体的操作——比如查天气、发邮件、读文件、调API、做计算——打包成一个模型可以理解、可以调用的单元。模型不需要知道这个操作底层是怎么实现的只需要知道“有这么个东西输入什么输出什么什么时候用”。这跟人类用工具的逻辑一模一样你不需要会造锤子你只需要知道锤子能钉钉子。那为什么是现在火因为Agent从“能聊天”进化到了“能干活”。过去大家玩模型主要是问答、生成、总结这些任务模型自己就能完成。但现在大家想让模型去操作真实系统帮你订机票、改代码、跑测试、发通知、做报表。这些任务光靠“说”是完不成的必须有人把“做”的部分封装好让模型能安全、可控地调用。skills就是干这个的。从热搜词也能看出来大家的关注点集中在几个方向Agent Skills的架构设计、Google Cloud和GKE上的部署、Genkit这类工具链的集成、以及各种具体场景下的skills开发与测试。有人关心怎么装有人关心怎么写有人关心怎么测还有人关心去哪里找现成的。这说明skills已经从概念讨论进入了工程落地阶段大家是真的在动手做了。这篇文章我会从实际开发者的视角把skills这件事拆开讲清楚。不管你是刚听说这个词想搞明白它是什么还是已经在写自己的skills但遇到了一些坑或者你在评估要不要把skills引入自己的项目下面这些内容应该都能给你一些参考。我会尽量少讲空话多讲我实际踩过的坑、试过的方案、以及那些文档里不会写的细节。2. 拆解Agent Skills的核心架构一个skill到底由什么组成2.1 从“模型只会说”到“模型能做事”的关键跨越要理解skills的架构先得理解一个根本问题模型为什么需要skills答案很简单因为模型本身是一个纯文本的输入输出系统。你给它一段文字它给你一段文字。它没有手没有眼睛没有记忆也不能直接操作任何外部系统。你让它“帮我查一下明天的天气”它只能根据训练数据里的知识瞎猜或者告诉你“我无法获取实时信息”。但如果你给它配一个“查天气”的skill情况就变了。这个skill会告诉模型有一个叫get_weather的工具接受一个城市名作为参数返回该城市当前的天气信息。模型看到这个描述后就知道当用户问天气时它可以调用这个工具把城市名传进去然后拿到真实数据。模型还是那个模型但它现在有了“手”。这个跨越看起来简单实际上涉及好几个层面的设计。第一你得让模型知道有哪些skill可用。第二你得让模型知道每个skill接受什么参数、返回什么结果。第三你得让模型知道什么时候该用哪个skill。第四你得有一个执行层真正去调用这些skill并把结果返回给模型。第五你还得处理错误、超时、权限、并发这些工程问题。这五个层面构成了Agent Skills的完整架构。缺了任何一个系统都跑不起来。我见过不少人只做了第一层和第四层结果模型要么不知道该用什么工具要么用错了参数要么在工具报错后完全不知道怎么处理。这些都是架构设计没做到位导致的。2.2 一个标准skill的解剖描述、参数、执行体、返回结构一个标准的skill通常包含四个核心部分。我用一个实际例子来说明假设我们要做一个“查询数据库”的skill。第一部分是描述description。这是给模型看的自然语言说明告诉它这个skill是干什么的。比如“根据SQL查询语句从业务数据库中获取数据支持SELECT语句返回查询结果集。”这段描述的质量直接决定了模型能不能在正确的场景下选中这个skill。描述写得太模糊模型就会乱用写得太窄模型又可能在该用的时候想不到它。第二部分是参数定义parameters。这是结构化的输入说明通常用JSON Schema来描述。比如这个查询skill需要一个sql参数类型是字符串必填并且要说明“只支持SELECT语句不支持UPDATE、DELETE等写操作”。参数定义要尽量精确包括类型、是否必填、默认值、取值范围、示例值。模型会根据这些信息来构造调用参数。第三部分是执行体executor。这是真正干活的代码。它接收模型传来的参数执行具体操作然后返回结果。执行体可以用任何语言写Python、JavaScript、Go都行关键是它要能被Agent框架调用。执行体内部要处理异常、超时、资源清理这些细节。第四部分是返回结构response schema。这是告诉模型“你会拿到什么样的结果”的说明。返回结构可以是纯文本也可以是结构化的JSON。如果是结构化的最好也给出schema这样模型能更好地解析和利用返回数据。把这四部分组合起来就是一个完整的skill。模型看到描述和参数定义决定要不要调用Agent框架负责把调用请求路由到执行体执行体跑完后把结果按返回结构传回去模型再根据结果决定下一步做什么。2.3 为什么说“描述质量”比“代码质量”更致命这是我踩过的最大的坑之一。刚开始写skills的时候我把大部分精力花在执行体的代码上觉得只要代码写得健壮、异常处理得好skill就没问题。结果上线后发现模型经常在该调用这个skill的时候不调用或者在不该调用的时候乱调用。排查了半天发现根因不在代码而在描述。模型选择skill的唯一依据就是描述。它看不到你的代码也不知道你的执行体写得多优雅。它只能根据描述来判断“这个skill是干什么的”“什么时候该用”“参数怎么填”。如果描述写得含糊模型就会做出错误的判断。举个例子我写过一个“发送通知”的skill描述写的是“发送消息给用户”。结果模型在用户只是问“帮我总结一下这篇文章”的时候也试图调用这个skill去“发送总结”。因为在它看来“发送消息”和“输出总结”好像差不多。后来我把描述改成“向指定用户发送站内通知消息仅在用户明确要求通知某人或系统需要主动推送提醒时使用”问题就解决了。所以我的经验是写描述的时间应该至少和执行体代码的时间一样多。描述要回答三个问题这个skill做什么、什么时候用、什么时候不用。特别是“什么时候不用”这一点很多人会忽略但它对减少误调用非常关键。2.4 参数设计的颗粒度太粗会失控太细会爆炸参数设计是另一个容易翻车的地方。参数太少模型没法精确控制skill的行为参数太多模型又容易填错或者不知道该填什么。我见过一个极端的例子有人做了一个“文件操作”的skill参数包括operation操作类型、path路径、content内容、encoding编码、mode模式、recursive是否递归、backup是否备份等等一共十几个参数。结果模型每次调用都要纠结半天经常把mode和operation搞混或者忘记填encoding导致乱码。后来我把它拆成了三个独立的skillread_file、write_file、list_files。每个skill只做一件事参数控制在三到五个以内。模型的选择准确率立刻上去了调用错误率也降下来了。所以参数设计的核心原则是一个skill只做一件事参数只保留完成这件事必需的。如果一个skill需要超过七个参数大概率应该拆成多个skill。如果某个参数在大多数调用中都用默认值那它可能不应该出现在参数列表里而是作为skill的固定配置。3. 从零开发一个skill完整流程与关键决策点3.1 环境准备选对框架比写对代码更重要动手写第一个skill之前先要决定用什么框架来承载它。目前市面上能跑Agent Skills的框架不少有偏轻量的有偏企业级的有跟云平台深度绑定的也有纯开源的。选哪个取决于你的使用场景和团队的技术栈。如果你只是想在本地快速验证一个想法那用一个轻量的Agent框架就够了。这类框架通常只需要几十行代码就能跑起来一个带skill的Agent适合做原型验证。缺点是生产环境下的可观测性、权限控制、并发处理这些能力比较弱。如果你是要在企业环境里部署那就需要考虑更完整的方案。比如Google Cloud上的GKE配合Genkit就是一套比较成熟的组合。GKE负责容器编排和弹性伸缩Genkit负责Agent逻辑和skill管理两者配合可以做到skill的独立部署、版本管理、灰度发布。这套方案的学习曲线陡一些但生产可用性明显更好。我个人的建议是先用轻量框架把skill的逻辑跑通验证描述和参数设计没问题然后再迁移到生产级框架上。不要一上来就搞全套基础设施那样很容易在还没搞清楚skill该怎么写的时候就被环境问题卡住。3.2 定义skill的输入输出用JSON Schema把话说清楚选好框架后第一件事是定义skill的输入输出。这一步看起来简单实际上决定了后面所有代码的结构。输入定义用JSON Schema来写要明确每个参数的类型、是否必填、取值范围、默认值、以及描述。描述要写给模型看所以要用自然语言不要用技术黑话。比如不要写“参数为string类型”要写“城市名称例如北京、上海、东京”。输出定义同样重要。如果skill返回的是结构化数据最好也给出schema这样模型能更好地理解返回结果。如果返回的是纯文本那要在描述里说明文本的格式和含义。这里有一个容易被忽略的点错误返回也要定义。skill执行失败时返回什么是抛异常还是返回一个包含错误信息的对象模型看到错误信息后应该怎么处理这些都要提前想清楚。我的做法是统一返回一个包含success、data、error三个字段的对象模型根据success判断是否成功根据error决定是否重试或换一种方式。3.3 编写执行体异常处理、超时控制、幂等性一个都不能少执行体是真正干活的代码也是最容易出问题的地方。我总结下来有三个点必须处理好。第一是异常处理。执行体内部可能因为各种原因失败网络超时、权限不足、参数非法、外部服务不可用。这些异常不能直接抛给模型因为模型看不懂堆栈信息。要把异常转换成模型能理解的错误描述比如“查询失败数据库连接超时请稍后重试”或者“参数错误城市名不能为空”。第二是超时控制。有些skill调用的外部服务可能很慢如果不设超时整个Agent流程就会被卡住。我的做法是给每个skill设置一个合理的超时时间比如五秒或十秒超时后返回一个明确的错误让模型决定是重试还是换方案。第三是幂等性。如果模型因为某种原因重复调用了同一个skill执行体应该能正确处理。比如“发送通知”这个skill如果模型不小心调了两次不应该给用户发两条通知。实现幂等性的方式有很多可以用请求ID去重也可以用状态标记。关键是设计skill的时候就要考虑这个问题不要等到线上出事了才补。3.4 注册与发现让模型知道有哪些skill可用skill写好后要注册到Agent框架里模型才能看到。注册的方式各框架不同但核心逻辑是一样的把skill的描述、参数定义、执行体入口注册到一个注册表里Agent在每次对话开始时把注册表里的skill列表传给模型。这里有一个实践中的坑skill数量多了之后模型的注意力会被分散。如果你注册了五十个skill模型在选择时准确率会明显下降。我的做法是分组注册根据当前对话的上下文动态加载相关的skill。比如用户在做数据分析就只加载数据处理相关的skill用户在做文本编辑就只加载文本操作相关的skill。这样模型的选择空间小了准确率就上去了。3.5 测试与调试怎么判断一个skill写得好不好skill写完后一定要测试。测试分两个层面功能测试和模型调用测试。功能测试是验证执行体本身有没有bug这个用常规的单元测试就行。模型调用测试是验证模型能不能在正确的场景下选中这个skill、能不能正确填充参数、能不能正确处理返回结果。这个测试更关键也更难做。我的做法是准备一组测试用例每个用例包含一段用户输入和期望的skill调用行为。比如用户说“帮我查一下北京明天的天气”期望模型调用get_weather参数是{city: 北京, date: 明天}。然后跑一遍看模型的实际行为是否符合预期。不符合的就调整描述或参数定义直到准确率达标。这个过程可能需要反复迭代很多次。我写第一个skill的时候改了七八版描述才把准确率调到可接受的水平。所以不要指望一次就能写对迭代是常态。4. 实操落地在GKE上部署Agent Skills的完整过程4.1 为什么选择GKE Genkit这套组合前面讲了skill的开发流程这一节讲部署。我选GKE加Genkit这套组合来演示原因有三个。第一GKE是容器编排的事实标准之一skill的执行体可以打包成容器独立部署每个skill有自己的资源配额、扩缩容策略和版本管理。这对于生产环境很重要因为不同skill的负载特征可能完全不同有的轻量高频有的重量低频混在一起部署会互相影响。第二Genkit提供了一套比较完整的Agent开发工具链包括skill注册、调用路由、可观测性、以及和模型API的集成。它跟GKE的配合也比较顺可以直接把Agent服务部署到GKE集群里。第三这套组合的文档和社区支持相对成熟遇到问题比较容易找到参考方案。当然这不是唯一的选择。如果你用的是其他云平台或者自建集群核心思路是一样的skill执行体容器化、独立部署、通过注册中心统一管理。下面我以GKE为例把关键步骤走一遍。4.2 容器化skill执行体Dockerfile的关键配置每个skill的执行体打包成一个独立的容器镜像。Dockerfile的写法跟普通服务差不多但有几个点要注意。基础镜像要选轻量的比如python:3.11-slim或者node:20-alpine减少镜像体积和启动时间。依赖要分层安装把不常变的部分放在前面利用Docker的缓存机制加速构建。启动命令要明确最好用一个轻量的HTTP服务器来暴露skill的调用接口比如FastAPI或者Express。一个典型的Dockerfile大概长这样FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install --no-cache-dir -r requirements.txt COPY . . EXPOSE 8080 CMD [uvicorn, main:app, --host, 0.0.0.0, --port, 8080]这里的关键是--no-cache-dir避免pip缓存把镜像撑大。另外EXPOSE的端口要和GKE的Service配置对上不然流量进不来。4.3 在GKE上创建Deployment和Service参数怎么定镜像推送到镜像仓库后就可以在GKE上创建Deployment了。Deployment的配置有几个关键参数需要根据skill的负载特征来定。replicas是副本数轻量高频的skill可以多设几个重量低频的设一两个就行。resources.requests和resources.limits是资源配额requests影响调度limits影响运行时上限。我的经验是requests设小一点limits设大一点给突发流量留余量。livenessProbe和readinessProbe是健康检查一定要配不然GKE不知道你的skill是不是还活着。Service的配置相对简单主要是把Deployment暴露成一个内部可访问的地址。如果Agent服务和skill在同一个集群里用ClusterIP就够了如果需要从集群外访问再用LoadBalancer或者Ingress。4.4 用Genkit注册skill代码示例与配置说明Genkit的skill注册逻辑比较直观。你定义一个skill对象包含名称、描述、参数schema和执行函数然后注册到Genkit的运行时里。import { genkit, skill } from genkit; const ai genkit({ plugins: [...] }); const getWeather skill({ name: get_weather, description: 查询指定城市的当前天气和未来预报, parameters: { type: object, properties: { city: { type: string, description: 城市名称例如北京、上海 }, date: { type: string, description: 日期格式YYYY-MM-DD默认为今天 } }, required: [city] }, handler: async ({ city, date }) { // 调用天气API返回结果 const result await weatherApi.query(city, date); return { success: true, data: result }; } }); ai.registerSkill(getWeather);注册完成后Genkit会自动把skill的描述和参数传给模型模型在需要时就会调用。这里要注意的是handler里的异常处理最好用try-catch包起来返回结构化的错误信息不要让异常直接抛出去。4.5 可观测性配置日志、指标、追踪一个都不能少生产环境跑skill可观测性是必须的。你需要知道每个skill被调用了多少次、成功率多少、平均耗时多少、错误分布是什么样的。这些数据不仅能帮你排查问题还能指导优化。GKE自带Cloud Logging和Cloud Monitoringskill执行体只要把日志打到标准输出就能自动被采集。指标方面可以用OpenTelemetry SDK在代码里埋点记录调用次数、耗时、错误数。追踪方面Genkit支持把每次skill调用串成一个trace方便你看到完整的调用链路。我的做法是在skill执行体的入口和出口各打一条日志记录请求参数和返回结果注意脱敏然后在关键步骤埋点记录耗时。这样出问题时能快速定位是哪个环节慢了或者挂了。5. 常见问题与排查技巧实录5.1 模型不调用skill或调用错误的skill这是最常见的问题没有之一。表现是模型在该用skill的时候不用或者用了错误的skill。根因通常出在描述上。排查思路是这样的先把模型看到的skill列表打印出来确认描述和参数定义是不是符合预期。然后拿几个典型用例跑一遍看模型的选择结果。如果发现某个skill经常被误选就检查它的描述是不是太宽泛或者跟其他skill的描述有重叠。如果某个skill该被选却没被选就检查它的描述是不是太窄或者关键词跟用户输入对不上。调整描述的时候有一个技巧很管用在描述里加入反例。比如“这个skill用于查询天气不用于查询股票、新闻或其他信息”。这样模型就能更清楚地区分不同skill的边界。5.2 参数填充错误或缺失模型有时候会填错参数比如把城市名填成省份名或者漏填必填参数。这个问题通常有两个原因一是参数描述不够清楚二是参数schema不够严格。解决办法是在参数描述里给出明确的示例和格式要求。比如不要只写“城市名称”要写“城市名称例如北京、上海、东京不要填省份或国家名称”。如果参数有固定取值范围用enum列出来。如果参数有格式要求用pattern约束。另外可以在执行体里加一层参数校验发现参数不合法时返回明确的错误信息让模型有机会重新填充。这比直接报错要好因为模型看到错误信息后可能会自我纠正。5.3 skill执行超时或返回异常skill执行超时通常是因为外部服务响应慢或者执行体里有阻塞操作。排查时先看日志确认是哪个环节慢。如果是外部服务的问题考虑加缓存或者换服务如果是执行体本身的问题考虑优化代码或者加异步处理。返回异常的情况比较复杂可能是执行体抛了未捕获的异常也可能是返回结构不符合预期。我的做法是在执行体最外层加一个统一的异常捕获把任何异常都转换成结构化的错误返回。同时在Agent框架层面加一个返回结构校验发现不符合schema的返回就打日志告警。5.4 skill数量增多后的管理难题当skill数量超过二十个之后管理就会变得困难。模型的选择准确率下降开发者也容易搞混不同skill的职责。我的应对策略是分组管理。把skill按业务领域分成若干组每组不超过十个。Agent在运行时根据上下文动态加载相关的组而不是一次性加载所有skill。这样既减少了模型的认知负担也让代码结构更清晰。另外建立一套skill的命名规范也很重要。比如用动词_名词的格式get_weather、send_notification、read_file一看就知道是干什么的。避免用tool1、helper这种无意义的名字。5.5 常见问题速查表问题现象可能原因排查方法解决思路模型不调用skill描述太窄或关键词不匹配打印skill列表跑典型用例调整描述加入用户可能说的关键词模型调用错误skill描述太宽或与其他skill重叠对比误选skill的描述收窄描述加入反例和边界说明参数填充错误参数描述不清晰或schema不严格检查参数定义和实际填充值补充示例用enum和pattern约束执行超时外部服务慢或代码阻塞看日志定位耗时环节加缓存、异步处理或换服务返回结构异常异常未捕获或schema不匹配检查执行体异常处理和返回校验统一异常捕获加返回结构校验skill数量多导致选择困难一次性加载太多skill统计模型选择准确率分组加载按上下文动态注册6. 进阶方向让skills从“能用”到“好用”6.1 skill的组合与编排多个skill如何协同完成复杂任务单个skill只能做一件事但真实任务往往需要多个skill配合。比如“帮我整理一份周报”可能需要先调用read_file读取本周的工作记录再调用summarize做摘要最后调用send_email发出去。这三个skill怎么串起来就是编排的问题。目前有两种主流的编排方式。一种是让模型自己决定调用顺序Agent框架只负责执行。这种方式灵活但模型可能会走弯路。另一种是预定义工作流把多个skill按固定顺序串起来模型只负责填充参数。这种方式可控但灵活性差。我的经验是混合使用对于流程固定的任务用预定义工作流对于需要灵活判断的任务让模型自己编排。关键是给模型足够的上下文让它知道当前处于流程的哪一步、下一步该做什么。6.2 skill的版本管理与灰度发布skill上线后难免要修改修改就可能引入回归问题。所以版本管理很重要。我的做法是给每个skill打版本号Agent框架支持按版本调用。新版本先在小流量上灰度观察一段时间没问题再全量。灰度发布的粒度可以按用户分也可以按请求分。按用户分适合做A/B测试按请求分适合做渐进式发布。关键是有一套监控机制能及时发现新版本的问题并自动回滚。6.3 安全与权限skill调用的边界控制skill能操作真实系统所以安全边界必须清晰。一个skill能访问哪些资源、能执行哪些操作、能返回哪些数据都要有明确的限制。我的做法是在skill注册时声明权限需求Agent框架在调用前做权限校验。比如一个“查询数据库”的skill只能执行SELECT语句不能执行UPDATE或DELETE。一个“发送通知”的skill只能给当前用户发通知不能给其他用户发。这些限制要写在执行体里不能只靠描述来约束模型。另外skill的返回数据也要做脱敏处理。不要把敏感信息直接返回给模型因为模型可能会把它写进日志或者输出给用户。该过滤的过滤该掩码的掩码。6.4 性能优化缓存、批处理、异步化skill的性能直接影响用户体验。优化手段主要有三个。缓存是最有效的。如果某个skill的调用结果在一段时间内不会变就把它缓存起来。比如“查询城市信息”这种skill同一个城市的结果可以缓存几分钟到几小时。缓存可以放在执行体内部也可以放在Agent框架层面。批处理适合一次要处理多个相似请求的场景。比如要查十个城市的天气不要调十次skill而是调一次skill传十个城市。这样能减少网络往返和模型调用次数。异步化适合耗时长的skill。如果某个skill要跑几十秒不要让模型干等而是先返回一个“任务已提交”的响应等任务完成后再通知模型。这样用户体验会好很多。6.5 从单Agent到多Agentskills在复杂系统中的应用当任务复杂度继续上升单个Agent可能就扛不住了。这时候需要多个Agent分工协作每个Agent负责一部分skill。比如一个Agent负责数据查询一个Agent负责内容生成一个Agent负责对外交互。它们之间通过消息传递来协调。这种架构下skill的管理会更复杂因为要决定哪个skill归哪个Agent管。我的做法是按业务领域划分每个Agent负责一个领域的skillAgent之间通过一个协调层来通信。协调层负责把任务拆解、分发给合适的Agent、收集结果、处理冲突。这套架构的复杂度明显更高适合任务边界清晰、skill数量多的场景。如果只是做一个小工具单Agent加几个skill就够了不要过度设计。7. 我个人的一些实操体会写了这么多最后分享几个我在实际开发中总结出来的、文档里不会写的点。第一个是先写描述再写代码。很多人习惯先把执行体写好再补描述。但描述才是模型看到的东西它决定了skill能不能被正确调用。所以我现在都是先写描述把“这个skill做什么、什么时候用、参数怎么填”想清楚再去写执行体。这样写出来的skill调用准确率明显更高。第二个是测试用例要覆盖边界情况。不要只测正常流程要测参数缺失、参数非法、外部服务超时、返回结果为空这些情况。模型在这些边界情况下的表现往往决定了整个系统的稳定性。第三个是日志要打全但不要打敏感信息。skill的输入输出都要打日志方便排查问题。但要注意脱敏不要把用户密码、token、个人隐私信息打进日志。这个坑我踩过后来花了不少时间做日志清洗。第四个是skill的粒度宁小勿大。一个skill只做一件事参数控制在五个以内。如果发现某个skill越来越复杂就拆。拆得越细模型的选择越准确维护也越容易。第五个是不要指望模型一次就选对。模型的选择准确率受很多因素影响描述、参数、上下文、甚至模型版本。所以要建立一套持续评估的机制定期跑测试用例发现准确率下降就及时调整。这是一个持续迭代的过程不是一劳永逸的。这套东西我前后折腾了大半年从最开始的一个skill都跑不通到现在能稳定管理几十个skill的Agent系统中间踩的坑不计其数。但回头看skills这个方向是对的。它把模型的能力边界从“说”扩展到了“做”让AI真正能参与到实际工作流里。如果你也在做类似的事情希望上面这些经验能帮你少走一些弯路。