1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区、开发者群聊还是各种项目讨论里“skills”这个词出现的频率高得离谱。你随便翻翻热搜能看到agent skills、codex skills、claude agent skills、skills开发、skills推荐这些词扎堆冒出来。很多人第一次看到会以为是某个新框架或者新语言其实不是——它更像是一种能力封装与复用机制把一组可执行的操作、工具调用、上下文约束打包成一个独立单元让智能体或者自动化流程能够按需加载、按需执行。我最早接触这个概念是在做一个自动化代码审查流程的时候。当时的需求很简单让一个智能体能够自动读取仓库里的变更、跑静态检查、生成审查意见、再把结果回写到合并请求里。听起来不复杂但真做起来你会发现每一步都涉及不同的工具、不同的权限、不同的上下文格式。如果每次都从头写一遍提示词和工具绑定维护成本高得吓人。后来我把这套流程拆成了几个独立的“skill”每个 skill 负责一个明确的动作需要的时候组合起来用整个系统的可维护性直接上了一个台阶。这就是 skills 的核心价值把“怎么做一件事”的知识和工具绑定在一起形成可复用、可组合、可独立测试的单元。它解决的不是某个具体的技术问题而是“如何让智能体稳定地完成一类任务”这个工程问题。适合谁来参考如果你正在做智能体应用、自动化工作流、代码生成工具、或者任何需要让模型按固定套路完成任务的系统那 skills 这套思路你绕不开。哪怕你只是好奇为什么大家都在聊这个理解它的设计逻辑也能帮你在选型时少走弯路。我下面会从设计思路、核心细节、实操过程、常见问题几个角度把 skills 这个东西拆开讲清楚。内容会涉及 Google Cloud、GKE、Genkit 这些具体平台和工具也会聊到 agent skills 的测试方法和开发要点。不管你是刚听说这个词还是已经在项目里用了一段时间应该都能找到对你有用的部分。2. 内容整体设计与思路拆解为什么是“技能”而不是“函数”或“插件”2.1 从函数调用到技能封装解决的是什么问题要理解 skills 的设计思路得先看它要解决什么问题。传统的函数调用或者工具调用模式是这样的你定义一个函数描述它的输入输出模型根据上下文决定什么时候调用它。这个模式在简单场景下很好用但一旦任务变复杂问题就来了。举个例子假设你要做一个“自动生成周报”的功能。传统做法可能是定义一个generate_weekly_report函数然后把所有逻辑塞进去。但这个函数内部要做的事情太多了读取本周的提交记录、过滤掉不重要的变更、按模块归类、生成自然语言描述、格式化成 Markdown、最后发送到指定渠道。任何一个环节出问题整个函数就失败了而且你很难定位到底是哪一步的问题。Skills 的思路是把这些步骤拆开。你可以有一个fetch_commitsskill、一个categorize_changesskill、一个generate_summaryskill、一个format_reportskill。每个 skill 独立定义、独立测试、独立版本管理。需要生成周报的时候按顺序调用这几个 skill 就行了。这样做的好处很明显每个 skill 的职责单一出问题容易定位可以单独替换某个 skill 而不影响其他部分不同项目之间可以复用同一个 skill。注意技能拆分不是越细越好。拆得太细会导致调用链过长上下文切换成本增加。我一般建议一个 skill 对应一个“有意义的动作单元”比如“读取文件”“调用某个 API”“生成一段结构化文本”而不是拆到“拼接字符串”这种粒度。2.2 为什么选择“技能”这个抽象层级你可能会问为什么不用插件或者中间件插件通常是绑定在某个宿主系统上的换一个环境就用不了。中间件更偏向请求处理管道不适合表达“完成一个任务需要哪些步骤”这种逻辑。Skills 的抽象层级刚好在两者之间它比函数调用更高级能表达多步操作和上下文依赖又比完整的智能体更轻量不需要自己管理对话状态和规划逻辑。从工程角度看这个抽象层级的好处是它天然适合组合。你可以把几个 skill 串成一个 pipeline也可以让模型根据当前上下文动态选择调用哪个 skill。这种灵活性在构建复杂智能体系统的时候特别重要。比如你在做一个代码助手用户可能让你“解释这段代码”“重构这个函数”“生成单元测试”这三个任务对应的 skill 完全不同但模型可以根据用户意图自动路由。另外skills 的设计通常会和具体的平台能力绑定。比如在 Google Cloud 的生态里一个 skill 可能封装了对 GKE 集群的操作、对 Cloud Storage 的读写、或者对 Genkit 流程的调用。这种绑定让 skill 不只是“提示词模板”而是真正能执行动作的单元。2.3 技能系统的核心组件有哪些一个完整的 skill 系统通常包含这几个部分技能定义描述这个技能做什么、需要什么输入、产生什么输出、依赖哪些工具或权限。技能注册与发现系统怎么知道有哪些技能可用怎么根据当前任务找到合适的技能。技能执行引擎负责实际调用技能处理输入输出转换、错误重试、超时控制。技能组合与编排多个技能如何按顺序或条件组合成一个更大的工作流。技能测试与验证怎么确认一个技能在给定输入下能产生预期输出。这五个部分缺一不可。我见过不少项目只做了技能定义和执行忽略了注册发现和测试验证结果技能一多就乱套了没人知道某个技能到底能不能用、什么时候该用。所以在设计初期就把这几个组件考虑进去后面会省很多事。2.4 和传统工作流引擎的区别在哪有人可能会说这不就是工作流引擎吗DAG、状态机、任务编排这些概念早就有了。确实有相似之处但关键区别在于skills 是面向模型设计的而不是面向人类开发者设计的。传统工作流引擎的节点通常需要精确的输入输出定义和条件分支而 skill 的设计允许一定程度的模糊性和自然语言描述因为调用方可能是模型而不是代码。这个区别带来两个重要影响。第一skill 的接口设计要更宽容不能要求调用方提供完全结构化的参数很多时候需要模型自己从上下文里提取。第二skill 的执行结果往往需要转换成模型能理解的格式而不是直接返回原始数据。这两点在设计 skill 的时候必须考虑进去否则模型用起来会很别扭。3. 核心细节解析与实操要点从定义到执行的关键环节3.1 技能定义怎么写才能让模型用对技能定义是整个系统的基础。写得好模型能准确调用写得不好模型要么不用要么乱用。我总结下来一个好的技能定义应该包含这几个要素名称简短、动词开头、能一眼看出做什么。比如fetch_github_issues就比issue_tool好。描述用自然语言说明这个技能解决什么问题、什么时候该用、什么时候不该用。描述里要包含触发条件比如“当用户需要获取仓库的未解决问题列表时使用”。输入参数每个参数要有名称、类型、是否必填、描述。描述里要说明参数的格式和取值范围。输出格式说明技能返回什么是文本、JSON 还是其他结构。依赖与权限这个技能需要访问哪些外部资源需要什么权限。示例给一两个调用示例帮助模型理解怎么用。我踩过的一个坑是描述写得太笼统。比如写“获取数据”模型根本不知道是获取什么数据、从哪获取、什么条件下该用。后来改成“从 GitHub 仓库获取指定标签的未关闭问题列表返回标题、编号和创建时间”调用准确率明显提升。提示技能描述里最好包含“不适用场景”。比如“这个技能只用于读取不用于修改或删除”。这样能防止模型在需要写操作的时候误用读技能。3.2 技能注册与发现怎么让系统知道有哪些技能可用技能注册有两种常见模式静态注册和动态发现。静态注册就是在系统启动时把所有技能加载进来适合技能数量不多、变动不频繁的场景。动态发现则是运行时从某个注册中心查询可用技能适合技能数量多、需要热更新的场景。在 Google Cloud 的生态里你可以用 GKE 上的服务来托管技能注册中心每个技能作为一个独立的微服务或者 Cloud Run 服务。Genkit 则提供了更轻量的方式把技能定义成 flow 的一部分通过 Genkit 的工具注册机制来管理。两种方式各有优劣GKE 方案更重但更灵活适合大规模生产环境Genkit 方案更轻但依赖框架适合快速原型和中小规模应用。我个人的经验是如果技能数量在 20 个以内静态注册完全够用没必要上动态发现。超过 50 个之后动态发现和版本管理就变得很重要了否则你会陷入“这个技能到底是最新版本还是旧版本”的混乱里。3.3 技能执行引擎的设计要点执行引擎是技能系统的核心。它要处理的事情包括参数校验、权限检查、实际调用、结果转换、错误处理、超时控制、日志记录。每一块都有讲究。参数校验不能太严也不能太松。太严了模型经常传不对参数太松了又容易出安全问题。我的做法是类型和必填项严格校验取值范围给默认值或者宽松处理。比如一个max_results参数类型必须是整数但如果不传就默认 10传了负数就取绝对值或者报错。权限检查是很多人容易忽略的。一个技能可能能访问敏感数据如果模型被诱导调用了这个技能后果可能很严重。所以每个技能都要明确声明需要的权限执行引擎在调用前检查当前上下文是否有这些权限。错误处理要区分可重试错误和不可重试错误。网络超时、限流这类错误可以重试参数错误、权限不足这类错误重试也没用。执行引擎要根据错误类型决定是否重试以及重试几次。3.4 技能组合与编排的常见模式技能组合有几种常见模式顺序执行A 完成后执行 BB 完成后执行 C。适合有明确依赖关系的任务。条件分支根据 A 的结果决定执行 B 还是 C。适合需要根据中间结果做决策的场景。并行执行A 和 B 同时执行都完成后执行 C。适合独立子任务。循环执行对列表中的每一项执行同一个技能。适合批量处理。在实际项目里这几种模式经常混着用。比如一个代码审查流程可能是先并行执行“读取变更”和“读取配置”然后顺序执行“静态检查”根据检查结果条件执行“生成意见”或“直接通过”最后循环执行“回写评论”。编排的难点不在于模式本身而在于状态管理和错误传播。一个技能失败了是整个流程失败还是跳过继续失败信息怎么传递给后续技能这些需要在设计编排逻辑的时候就想清楚。3.5 技能测试怎么确认一个技能真的能用技能测试和普通单元测试不太一样。普通单元测试关注输入输出是否匹配技能测试还要关注模型能不能正确调用这个技能。我一般会做三层测试第一层是接口测试直接调用技能的执行函数验证输入输出是否符合预期。这层和普通单元测试类似。第二层是调用测试给模型一个需要用到这个技能的任务描述看模型能不能正确选择并调用这个技能。这层测试的是技能定义的质量。第三层是端到端测试把技能放到完整的智能体流程里看整个系统能不能完成任务。这层测试的是技能组合和编排的逻辑。三层测试都通过才能说这个技能是“可用”的。只做第一层的话经常会出现“技能本身没问题但模型不会用”的情况。4. 实操过程与核心环节实现从零搭一个技能系统4.1 环境准备与基础依赖假设我们要在 Google Cloud 上搭一个技能系统用 GKE 做技能托管用 Genkit 做技能编排。基础环境需要这些东西一个 GKE 集群至少两个节点每个节点 4 核 8G 起步。一个 Artifact Registry 仓库用来存技能镜像。一个 Cloud Storage 桶用来存技能定义和配置。Genkit 的开发环境Node.js 20 以上或者 Python 3.11 以上。GKE 集群的配置我建议开自动扩缩容最小节点数设 2最大设 10。技能服务的资源请求设 500m CPU 和 512Mi 内存限制设 1 CPU 和 1Gi 内存。这个配置对大多数技能来说够用了如果某个技能特别重可以单独给它更高的配额。Genkit 的安装很简单用 npm 或者 pip 装就行。装完之后初始化一个项目你会得到一个基础的 flow 结构。技能定义就放在这个 flow 里通过 Genkit 的工具注册机制暴露出去。4.2 定义一个基础技能以“读取 GKE 集群状态”为例我们从一个最简单的技能开始读取 GKE 集群的节点状态。这个技能的定义大概长这样name: get_gke_node_status description: 获取指定 GKE 集群的节点状态包括节点名称、状态、CPU 和内存使用率。当用户需要了解集群健康状态时使用。 input: cluster_name: type: string required: true description: GKE 集群的名称 zone: type: string required: true description: 集群所在的区域 output: type: array items: node_name: string status: string cpu_usage: number memory_usage: number permissions: - gke.read这个定义里description写清楚了什么时候用input和output定义了数据结构permissions声明了需要的权限。模型看到这个定义就知道在用户问“集群节点怎么样”的时候该调用它。实现这个技能的时候实际逻辑就是调用 GKE API 获取节点列表然后提取需要的信息。这里要注意的是错误处理如果集群不存在或者没有权限要返回明确的错误信息而不是让异常直接抛出去。模型看到明确的错误信息才能决定下一步怎么做。4.3 技能编排把多个技能串成一个工作流有了基础技能之后我们可以把它们串起来做一个更复杂的任务。比如“检查集群健康状态并在异常时发送通知”这个任务可以拆成三个技能get_gke_node_status、analyze_health、send_notification。在 Genkit 里这个编排可以写成一个 flowimport { genkit, z } from genkit; import { googleAI } from genkit-ai/googleai; const ai genkit({ plugins: [googleAI()] }); const healthCheckFlow ai.defineFlow({ name: healthCheck, inputSchema: z.object({ clusterName: z.string(), zone: z.string(), }), outputSchema: z.object({ status: z.string(), issues: z.array(z.string()), }), }, async (input) { const nodeStatus await getGkeNodeStatus(input.clusterName, input.zone); const analysis await analyzeHealth(nodeStatus); if (analysis.issues.length 0) { await sendNotification(analysis.issues); } return analysis; });这个 flow 里三个技能按顺序执行中间结果传递给下一个技能。analyzeHealth技能内部可以用模型来判断节点状态是否正常比如 CPU 使用率超过 80% 就标记为异常。sendNotification技能负责把异常信息发到指定渠道。注意编排的时候要考虑超时。每个技能设置合理的超时时间整个 flow 也要有总超时。否则一个技能卡住整个流程就挂了。4.4 技能版本管理与灰度发布技能上线之后难免要修改。修改的时候怎么保证不影响正在使用旧版本的系统答案是版本管理。每个技能定义里加一个version字段注册中心同时保留多个版本。调用方可以指定用哪个版本不指定就用最新稳定版。灰度发布的做法是新版本先注册但不设为默认让一部分调用方显式指定新版本观察一段时间没问题再设为默认。如果出问题把默认版本切回旧版本就行。在 GKE 上做灰度发布可以利用 Kubernetes 的 Service 和 Deployment 机制。每个技能版本对应一个 DeploymentService 根据标签路由流量。通过调整标签比例来控制灰度范围。4.5 监控与日志怎么知道技能在线上跑得怎么样技能上线之后监控是必须的。我一般会关注这几个指标调用次数每个技能被调用了多少次哪些技能没人用。成功率调用成功和失败的比例失败的原因分布。延迟每个技能的 P50、P95、P99 延迟。模型调用准确率模型选择这个技能的准确率有没有该用没用或者不该用乱用的情况。日志方面每次技能调用都要记录调用时间、调用方、输入参数、输出结果、耗时、错误信息。这些日志不仅用于排查问题还能用来优化技能定义。比如你发现某个技能经常被传错参数说明参数描述需要改。在 GKE 上可以用 Cloud Logging 和 Cloud Monitoring 来收集这些指标和日志。Genkit 也内置了一些可观测性功能可以导出到 OpenTelemetry 兼容的后端。5. 常见问题与排查技巧实录踩过的坑和解决方案5.1 模型不调用技能或者调用错误的技能这是最常见的问题。表现是模型要么直接用自己的知识回答要么调用了不相关的技能。原因通常有三个技能描述不清楚、技能名称有歧义、或者上下文里没有足够的信息让模型判断该用哪个技能。排查的时候先看技能描述。把描述给一个不了解这个系统的人看问他“什么情况下你会用这个技能”如果他说不出来说明描述有问题。然后看技能名称有没有和其他技能混淆的可能。最后看调用时的上下文是不是缺少了必要的背景信息。解决方法是描述里加触发条件和不适用场景名称用动词开头且尽量具体上下文里补充必要的背景。我试过在描述里加一句“当用户明确提到‘集群节点’时使用”调用准确率提升了不少。5.2 技能执行超时或者卡死技能执行超时通常是因为依赖的外部服务响应慢或者技能内部逻辑有死循环。排查的时候先看日志确认卡在哪一步。如果是外部服务慢考虑加缓存或者异步处理。如果是内部逻辑问题加超时控制和重试机制。我遇到过一次技能卡死是因为调用了一个没有设置超时的 HTTP 请求对方服务挂了但连接没断请求一直挂着。后来给所有外部调用都加了超时问题就解决了。提示技能执行引擎一定要有强制超时机制不能依赖技能自己处理超时。有些技能实现可能忘了设超时引擎层面兜底能避免整个系统被拖垮。5.3 技能之间的数据格式不匹配多个技能组合的时候前一个技能的输出格式和后一个技能的输入格式对不上这是很常见的问题。比如 A 技能返回的是 JSON 对象B 技能期望的是字符串中间就需要转换。解决方法是在技能定义里明确输出格式编排的时候加转换层。如果转换逻辑复杂可以单独做一个转换技能。另外尽量让技能之间的数据格式统一比如都用 JSON减少转换的需要。5.4 技能权限管理混乱技能多了之后权限管理容易乱。有的技能权限给多了有的给少了导致调用失败。我的做法是每个技能只申请它真正需要的权限权限检查在执行引擎层面统一做。技能定义里声明权限执行引擎在调用前检查当前上下文是否有这些权限。这样权限逻辑集中在一处不容易出错。另外定期审查技能权限把不再需要的权限去掉。我见过一个项目半年前加的一个权限一直没去掉后来那个权限对应的资源已经不存在了但权限还在造成了安全隐患。5.5 技能测试覆盖率不够导致线上问题技能测试经常被忽略因为写测试比较麻烦。但不写测试的后果是线上问题频发。我的经验是至少要有接口测试和调用测试端到端测试可以按需做。接口测试保证技能本身逻辑正确调用测试保证模型能用对。这两个测试写起来不复杂但能挡住大部分问题。测试数据要覆盖正常情况和异常情况。正常情况包括典型输入和边界输入异常情况包括空输入、格式错误的输入、权限不足的情况。异常情况的测试特别重要因为线上出问题往往就是异常情况没处理好。问题类型典型表现排查方向解决方案模型不调用技能直接回答或调用错误技能检查技能描述和名称补充触发条件名称具体化技能执行超时调用长时间无响应查看日志定位卡点加超时控制优化外部依赖数据格式不匹配技能间传递数据报错检查输入输出定义加转换层统一数据格式权限管理混乱调用失败或权限过大审查技能权限声明最小权限原则集中检查测试覆盖不足线上问题频发检查测试用例补接口测试和调用测试5.6 技能数量膨胀后的管理问题技能数量多了之后管理会变得困难。命名冲突、功能重叠、版本混乱这些问题都会出现。我的做法是建立技能目录按功能域分类定期清理不再使用的技能。技能命名加前缀比如gke_开头的都是 GKE 相关技能。版本管理用语义化版本号重大变更升主版本功能新增升次版本修复升补丁版本。另外技能注册中心要支持搜索和过滤否则找技能全靠记忆效率很低。Genkit 的工具列表功能可以按名称和描述搜索GKE 方案可以自己做一个简单的搜索接口。6. 技能系统的扩展方向与个人经验分享6.1 从单机技能到分布式技能市场当技能数量超过一定规模单机管理就不够用了。这时候可以考虑做一个技能市场让不同团队贡献和共享技能。技能市场需要解决几个问题技能发现、版本兼容、权限隔离、质量评估。技能发现靠搜索和分类版本兼容靠语义化版本和依赖声明权限隔离靠命名空间和访问控制质量评估靠使用数据、评分和评论。这些机制建起来之后技能就能像软件包一样被复用整个组织的效率会提升很多。6.2 技能与智能体框架的深度集成Skills 不是孤立存在的它需要和智能体框架深度集成才能发挥最大价值。集成的关键在于框架能自动发现可用技能、根据任务动态选择技能、处理技能执行中的错误和重试、把技能结果融入对话上下文。不同的智能体框架集成方式不同。有的框架原生支持技能概念有的需要自己写适配层。选框架的时候要考虑这一点否则后期集成会很痛苦。6.3 技能开发的工程化实践技能开发要像软件开发一样工程化。版本控制、代码审查、自动化测试、持续集成、持续部署这些实践都要有。我见过不少团队把技能当成“提示词”来管理改了就改没有版本记录出了问题也不知道改了什么。这种做法的代价是系统越来越不可维护。我的建议是技能定义和实现都放在 Git 仓库里每次修改走合并请求流程自动化测试通过才能合并合并后自动部署到技能注册中心。这样整个流程可追溯、可回滚出了问题能快速定位。6.4 我个人在实际操作中的体会做了几个技能系统之后我最大的体会是技能设计的关键不在于技术实现而在于对任务的理解。一个技能好不好用取决于设计者是否真正理解这个任务在什么场景下被使用、使用者期望什么结果、可能遇到什么异常。技术实现只是把这些理解翻译成代码。另一个体会是不要追求一步到位。技能系统是演进而来的不是设计出来的。先做几个核心技能用起来发现问题再调整。我见过一些团队一开始就想设计一个完美的技能体系结果设计了好几个月还没上线最后不了了之。反而是那些先做起来再迭代的团队技能系统越用越顺手。最后分享一个小技巧给每个技能写一个“使用场景”文档用自然语言描述什么情况下该用这个技能、什么情况下不该用、常见的使用模式是什么。这个文档不参与技能定义但对团队协作特别有用。新成员加入的时候看这个文档比看代码快得多。
1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区、开发者群聊还是各种项目讨论里“skills”这个词出现的频率高得离谱。你随便翻翻热搜能看到agent skills、codex skills、claude agent skills、skills开发、skills推荐这些词扎堆冒出来。很多人第一次看到会以为是某个新框架或者新语言其实不是——它更像是一种能力封装与复用机制把一组可执行的操作、工具调用、上下文约束打包成一个独立单元让智能体或者自动化流程能够按需加载、按需执行。我最早接触这个概念是在做一个自动化代码审查流程的时候。当时的需求很简单让一个智能体能够自动读取仓库里的变更、跑静态检查、生成审查意见、再把结果回写到合并请求里。听起来不复杂但真做起来你会发现每一步都涉及不同的工具、不同的权限、不同的上下文格式。如果每次都从头写一遍提示词和工具绑定维护成本高得吓人。后来我把这套流程拆成了几个独立的“skill”每个 skill 负责一个明确的动作需要的时候组合起来用整个系统的可维护性直接上了一个台阶。这就是 skills 的核心价值把“怎么做一件事”的知识和工具绑定在一起形成可复用、可组合、可独立测试的单元。它解决的不是某个具体的技术问题而是“如何让智能体稳定地完成一类任务”这个工程问题。适合谁来参考如果你正在做智能体应用、自动化工作流、代码生成工具、或者任何需要让模型按固定套路完成任务的系统那 skills 这套思路你绕不开。哪怕你只是好奇为什么大家都在聊这个理解它的设计逻辑也能帮你在选型时少走弯路。我下面会从设计思路、核心细节、实操过程、常见问题几个角度把 skills 这个东西拆开讲清楚。内容会涉及 Google Cloud、GKE、Genkit 这些具体平台和工具也会聊到 agent skills 的测试方法和开发要点。不管你是刚听说这个词还是已经在项目里用了一段时间应该都能找到对你有用的部分。2. 内容整体设计与思路拆解为什么是“技能”而不是“函数”或“插件”2.1 从函数调用到技能封装解决的是什么问题要理解 skills 的设计思路得先看它要解决什么问题。传统的函数调用或者工具调用模式是这样的你定义一个函数描述它的输入输出模型根据上下文决定什么时候调用它。这个模式在简单场景下很好用但一旦任务变复杂问题就来了。举个例子假设你要做一个“自动生成周报”的功能。传统做法可能是定义一个generate_weekly_report函数然后把所有逻辑塞进去。但这个函数内部要做的事情太多了读取本周的提交记录、过滤掉不重要的变更、按模块归类、生成自然语言描述、格式化成 Markdown、最后发送到指定渠道。任何一个环节出问题整个函数就失败了而且你很难定位到底是哪一步的问题。Skills 的思路是把这些步骤拆开。你可以有一个fetch_commitsskill、一个categorize_changesskill、一个generate_summaryskill、一个format_reportskill。每个 skill 独立定义、独立测试、独立版本管理。需要生成周报的时候按顺序调用这几个 skill 就行了。这样做的好处很明显每个 skill 的职责单一出问题容易定位可以单独替换某个 skill 而不影响其他部分不同项目之间可以复用同一个 skill。注意技能拆分不是越细越好。拆得太细会导致调用链过长上下文切换成本增加。我一般建议一个 skill 对应一个“有意义的动作单元”比如“读取文件”“调用某个 API”“生成一段结构化文本”而不是拆到“拼接字符串”这种粒度。2.2 为什么选择“技能”这个抽象层级你可能会问为什么不用插件或者中间件插件通常是绑定在某个宿主系统上的换一个环境就用不了。中间件更偏向请求处理管道不适合表达“完成一个任务需要哪些步骤”这种逻辑。Skills 的抽象层级刚好在两者之间它比函数调用更高级能表达多步操作和上下文依赖又比完整的智能体更轻量不需要自己管理对话状态和规划逻辑。从工程角度看这个抽象层级的好处是它天然适合组合。你可以把几个 skill 串成一个 pipeline也可以让模型根据当前上下文动态选择调用哪个 skill。这种灵活性在构建复杂智能体系统的时候特别重要。比如你在做一个代码助手用户可能让你“解释这段代码”“重构这个函数”“生成单元测试”这三个任务对应的 skill 完全不同但模型可以根据用户意图自动路由。另外skills 的设计通常会和具体的平台能力绑定。比如在 Google Cloud 的生态里一个 skill 可能封装了对 GKE 集群的操作、对 Cloud Storage 的读写、或者对 Genkit 流程的调用。这种绑定让 skill 不只是“提示词模板”而是真正能执行动作的单元。2.3 技能系统的核心组件有哪些一个完整的 skill 系统通常包含这几个部分技能定义描述这个技能做什么、需要什么输入、产生什么输出、依赖哪些工具或权限。技能注册与发现系统怎么知道有哪些技能可用怎么根据当前任务找到合适的技能。技能执行引擎负责实际调用技能处理输入输出转换、错误重试、超时控制。技能组合与编排多个技能如何按顺序或条件组合成一个更大的工作流。技能测试与验证怎么确认一个技能在给定输入下能产生预期输出。这五个部分缺一不可。我见过不少项目只做了技能定义和执行忽略了注册发现和测试验证结果技能一多就乱套了没人知道某个技能到底能不能用、什么时候该用。所以在设计初期就把这几个组件考虑进去后面会省很多事。2.4 和传统工作流引擎的区别在哪有人可能会说这不就是工作流引擎吗DAG、状态机、任务编排这些概念早就有了。确实有相似之处但关键区别在于skills 是面向模型设计的而不是面向人类开发者设计的。传统工作流引擎的节点通常需要精确的输入输出定义和条件分支而 skill 的设计允许一定程度的模糊性和自然语言描述因为调用方可能是模型而不是代码。这个区别带来两个重要影响。第一skill 的接口设计要更宽容不能要求调用方提供完全结构化的参数很多时候需要模型自己从上下文里提取。第二skill 的执行结果往往需要转换成模型能理解的格式而不是直接返回原始数据。这两点在设计 skill 的时候必须考虑进去否则模型用起来会很别扭。3. 核心细节解析与实操要点从定义到执行的关键环节3.1 技能定义怎么写才能让模型用对技能定义是整个系统的基础。写得好模型能准确调用写得不好模型要么不用要么乱用。我总结下来一个好的技能定义应该包含这几个要素名称简短、动词开头、能一眼看出做什么。比如fetch_github_issues就比issue_tool好。描述用自然语言说明这个技能解决什么问题、什么时候该用、什么时候不该用。描述里要包含触发条件比如“当用户需要获取仓库的未解决问题列表时使用”。输入参数每个参数要有名称、类型、是否必填、描述。描述里要说明参数的格式和取值范围。输出格式说明技能返回什么是文本、JSON 还是其他结构。依赖与权限这个技能需要访问哪些外部资源需要什么权限。示例给一两个调用示例帮助模型理解怎么用。我踩过的一个坑是描述写得太笼统。比如写“获取数据”模型根本不知道是获取什么数据、从哪获取、什么条件下该用。后来改成“从 GitHub 仓库获取指定标签的未关闭问题列表返回标题、编号和创建时间”调用准确率明显提升。提示技能描述里最好包含“不适用场景”。比如“这个技能只用于读取不用于修改或删除”。这样能防止模型在需要写操作的时候误用读技能。3.2 技能注册与发现怎么让系统知道有哪些技能可用技能注册有两种常见模式静态注册和动态发现。静态注册就是在系统启动时把所有技能加载进来适合技能数量不多、变动不频繁的场景。动态发现则是运行时从某个注册中心查询可用技能适合技能数量多、需要热更新的场景。在 Google Cloud 的生态里你可以用 GKE 上的服务来托管技能注册中心每个技能作为一个独立的微服务或者 Cloud Run 服务。Genkit 则提供了更轻量的方式把技能定义成 flow 的一部分通过 Genkit 的工具注册机制来管理。两种方式各有优劣GKE 方案更重但更灵活适合大规模生产环境Genkit 方案更轻但依赖框架适合快速原型和中小规模应用。我个人的经验是如果技能数量在 20 个以内静态注册完全够用没必要上动态发现。超过 50 个之后动态发现和版本管理就变得很重要了否则你会陷入“这个技能到底是最新版本还是旧版本”的混乱里。3.3 技能执行引擎的设计要点执行引擎是技能系统的核心。它要处理的事情包括参数校验、权限检查、实际调用、结果转换、错误处理、超时控制、日志记录。每一块都有讲究。参数校验不能太严也不能太松。太严了模型经常传不对参数太松了又容易出安全问题。我的做法是类型和必填项严格校验取值范围给默认值或者宽松处理。比如一个max_results参数类型必须是整数但如果不传就默认 10传了负数就取绝对值或者报错。权限检查是很多人容易忽略的。一个技能可能能访问敏感数据如果模型被诱导调用了这个技能后果可能很严重。所以每个技能都要明确声明需要的权限执行引擎在调用前检查当前上下文是否有这些权限。错误处理要区分可重试错误和不可重试错误。网络超时、限流这类错误可以重试参数错误、权限不足这类错误重试也没用。执行引擎要根据错误类型决定是否重试以及重试几次。3.4 技能组合与编排的常见模式技能组合有几种常见模式顺序执行A 完成后执行 BB 完成后执行 C。适合有明确依赖关系的任务。条件分支根据 A 的结果决定执行 B 还是 C。适合需要根据中间结果做决策的场景。并行执行A 和 B 同时执行都完成后执行 C。适合独立子任务。循环执行对列表中的每一项执行同一个技能。适合批量处理。在实际项目里这几种模式经常混着用。比如一个代码审查流程可能是先并行执行“读取变更”和“读取配置”然后顺序执行“静态检查”根据检查结果条件执行“生成意见”或“直接通过”最后循环执行“回写评论”。编排的难点不在于模式本身而在于状态管理和错误传播。一个技能失败了是整个流程失败还是跳过继续失败信息怎么传递给后续技能这些需要在设计编排逻辑的时候就想清楚。3.5 技能测试怎么确认一个技能真的能用技能测试和普通单元测试不太一样。普通单元测试关注输入输出是否匹配技能测试还要关注模型能不能正确调用这个技能。我一般会做三层测试第一层是接口测试直接调用技能的执行函数验证输入输出是否符合预期。这层和普通单元测试类似。第二层是调用测试给模型一个需要用到这个技能的任务描述看模型能不能正确选择并调用这个技能。这层测试的是技能定义的质量。第三层是端到端测试把技能放到完整的智能体流程里看整个系统能不能完成任务。这层测试的是技能组合和编排的逻辑。三层测试都通过才能说这个技能是“可用”的。只做第一层的话经常会出现“技能本身没问题但模型不会用”的情况。4. 实操过程与核心环节实现从零搭一个技能系统4.1 环境准备与基础依赖假设我们要在 Google Cloud 上搭一个技能系统用 GKE 做技能托管用 Genkit 做技能编排。基础环境需要这些东西一个 GKE 集群至少两个节点每个节点 4 核 8G 起步。一个 Artifact Registry 仓库用来存技能镜像。一个 Cloud Storage 桶用来存技能定义和配置。Genkit 的开发环境Node.js 20 以上或者 Python 3.11 以上。GKE 集群的配置我建议开自动扩缩容最小节点数设 2最大设 10。技能服务的资源请求设 500m CPU 和 512Mi 内存限制设 1 CPU 和 1Gi 内存。这个配置对大多数技能来说够用了如果某个技能特别重可以单独给它更高的配额。Genkit 的安装很简单用 npm 或者 pip 装就行。装完之后初始化一个项目你会得到一个基础的 flow 结构。技能定义就放在这个 flow 里通过 Genkit 的工具注册机制暴露出去。4.2 定义一个基础技能以“读取 GKE 集群状态”为例我们从一个最简单的技能开始读取 GKE 集群的节点状态。这个技能的定义大概长这样name: get_gke_node_status description: 获取指定 GKE 集群的节点状态包括节点名称、状态、CPU 和内存使用率。当用户需要了解集群健康状态时使用。 input: cluster_name: type: string required: true description: GKE 集群的名称 zone: type: string required: true description: 集群所在的区域 output: type: array items: node_name: string status: string cpu_usage: number memory_usage: number permissions: - gke.read这个定义里description写清楚了什么时候用input和output定义了数据结构permissions声明了需要的权限。模型看到这个定义就知道在用户问“集群节点怎么样”的时候该调用它。实现这个技能的时候实际逻辑就是调用 GKE API 获取节点列表然后提取需要的信息。这里要注意的是错误处理如果集群不存在或者没有权限要返回明确的错误信息而不是让异常直接抛出去。模型看到明确的错误信息才能决定下一步怎么做。4.3 技能编排把多个技能串成一个工作流有了基础技能之后我们可以把它们串起来做一个更复杂的任务。比如“检查集群健康状态并在异常时发送通知”这个任务可以拆成三个技能get_gke_node_status、analyze_health、send_notification。在 Genkit 里这个编排可以写成一个 flowimport { genkit, z } from genkit; import { googleAI } from genkit-ai/googleai; const ai genkit({ plugins: [googleAI()] }); const healthCheckFlow ai.defineFlow({ name: healthCheck, inputSchema: z.object({ clusterName: z.string(), zone: z.string(), }), outputSchema: z.object({ status: z.string(), issues: z.array(z.string()), }), }, async (input) { const nodeStatus await getGkeNodeStatus(input.clusterName, input.zone); const analysis await analyzeHealth(nodeStatus); if (analysis.issues.length 0) { await sendNotification(analysis.issues); } return analysis; });这个 flow 里三个技能按顺序执行中间结果传递给下一个技能。analyzeHealth技能内部可以用模型来判断节点状态是否正常比如 CPU 使用率超过 80% 就标记为异常。sendNotification技能负责把异常信息发到指定渠道。注意编排的时候要考虑超时。每个技能设置合理的超时时间整个 flow 也要有总超时。否则一个技能卡住整个流程就挂了。4.4 技能版本管理与灰度发布技能上线之后难免要修改。修改的时候怎么保证不影响正在使用旧版本的系统答案是版本管理。每个技能定义里加一个version字段注册中心同时保留多个版本。调用方可以指定用哪个版本不指定就用最新稳定版。灰度发布的做法是新版本先注册但不设为默认让一部分调用方显式指定新版本观察一段时间没问题再设为默认。如果出问题把默认版本切回旧版本就行。在 GKE 上做灰度发布可以利用 Kubernetes 的 Service 和 Deployment 机制。每个技能版本对应一个 DeploymentService 根据标签路由流量。通过调整标签比例来控制灰度范围。4.5 监控与日志怎么知道技能在线上跑得怎么样技能上线之后监控是必须的。我一般会关注这几个指标调用次数每个技能被调用了多少次哪些技能没人用。成功率调用成功和失败的比例失败的原因分布。延迟每个技能的 P50、P95、P99 延迟。模型调用准确率模型选择这个技能的准确率有没有该用没用或者不该用乱用的情况。日志方面每次技能调用都要记录调用时间、调用方、输入参数、输出结果、耗时、错误信息。这些日志不仅用于排查问题还能用来优化技能定义。比如你发现某个技能经常被传错参数说明参数描述需要改。在 GKE 上可以用 Cloud Logging 和 Cloud Monitoring 来收集这些指标和日志。Genkit 也内置了一些可观测性功能可以导出到 OpenTelemetry 兼容的后端。5. 常见问题与排查技巧实录踩过的坑和解决方案5.1 模型不调用技能或者调用错误的技能这是最常见的问题。表现是模型要么直接用自己的知识回答要么调用了不相关的技能。原因通常有三个技能描述不清楚、技能名称有歧义、或者上下文里没有足够的信息让模型判断该用哪个技能。排查的时候先看技能描述。把描述给一个不了解这个系统的人看问他“什么情况下你会用这个技能”如果他说不出来说明描述有问题。然后看技能名称有没有和其他技能混淆的可能。最后看调用时的上下文是不是缺少了必要的背景信息。解决方法是描述里加触发条件和不适用场景名称用动词开头且尽量具体上下文里补充必要的背景。我试过在描述里加一句“当用户明确提到‘集群节点’时使用”调用准确率提升了不少。5.2 技能执行超时或者卡死技能执行超时通常是因为依赖的外部服务响应慢或者技能内部逻辑有死循环。排查的时候先看日志确认卡在哪一步。如果是外部服务慢考虑加缓存或者异步处理。如果是内部逻辑问题加超时控制和重试机制。我遇到过一次技能卡死是因为调用了一个没有设置超时的 HTTP 请求对方服务挂了但连接没断请求一直挂着。后来给所有外部调用都加了超时问题就解决了。提示技能执行引擎一定要有强制超时机制不能依赖技能自己处理超时。有些技能实现可能忘了设超时引擎层面兜底能避免整个系统被拖垮。5.3 技能之间的数据格式不匹配多个技能组合的时候前一个技能的输出格式和后一个技能的输入格式对不上这是很常见的问题。比如 A 技能返回的是 JSON 对象B 技能期望的是字符串中间就需要转换。解决方法是在技能定义里明确输出格式编排的时候加转换层。如果转换逻辑复杂可以单独做一个转换技能。另外尽量让技能之间的数据格式统一比如都用 JSON减少转换的需要。5.4 技能权限管理混乱技能多了之后权限管理容易乱。有的技能权限给多了有的给少了导致调用失败。我的做法是每个技能只申请它真正需要的权限权限检查在执行引擎层面统一做。技能定义里声明权限执行引擎在调用前检查当前上下文是否有这些权限。这样权限逻辑集中在一处不容易出错。另外定期审查技能权限把不再需要的权限去掉。我见过一个项目半年前加的一个权限一直没去掉后来那个权限对应的资源已经不存在了但权限还在造成了安全隐患。5.5 技能测试覆盖率不够导致线上问题技能测试经常被忽略因为写测试比较麻烦。但不写测试的后果是线上问题频发。我的经验是至少要有接口测试和调用测试端到端测试可以按需做。接口测试保证技能本身逻辑正确调用测试保证模型能用对。这两个测试写起来不复杂但能挡住大部分问题。测试数据要覆盖正常情况和异常情况。正常情况包括典型输入和边界输入异常情况包括空输入、格式错误的输入、权限不足的情况。异常情况的测试特别重要因为线上出问题往往就是异常情况没处理好。问题类型典型表现排查方向解决方案模型不调用技能直接回答或调用错误技能检查技能描述和名称补充触发条件名称具体化技能执行超时调用长时间无响应查看日志定位卡点加超时控制优化外部依赖数据格式不匹配技能间传递数据报错检查输入输出定义加转换层统一数据格式权限管理混乱调用失败或权限过大审查技能权限声明最小权限原则集中检查测试覆盖不足线上问题频发检查测试用例补接口测试和调用测试5.6 技能数量膨胀后的管理问题技能数量多了之后管理会变得困难。命名冲突、功能重叠、版本混乱这些问题都会出现。我的做法是建立技能目录按功能域分类定期清理不再使用的技能。技能命名加前缀比如gke_开头的都是 GKE 相关技能。版本管理用语义化版本号重大变更升主版本功能新增升次版本修复升补丁版本。另外技能注册中心要支持搜索和过滤否则找技能全靠记忆效率很低。Genkit 的工具列表功能可以按名称和描述搜索GKE 方案可以自己做一个简单的搜索接口。6. 技能系统的扩展方向与个人经验分享6.1 从单机技能到分布式技能市场当技能数量超过一定规模单机管理就不够用了。这时候可以考虑做一个技能市场让不同团队贡献和共享技能。技能市场需要解决几个问题技能发现、版本兼容、权限隔离、质量评估。技能发现靠搜索和分类版本兼容靠语义化版本和依赖声明权限隔离靠命名空间和访问控制质量评估靠使用数据、评分和评论。这些机制建起来之后技能就能像软件包一样被复用整个组织的效率会提升很多。6.2 技能与智能体框架的深度集成Skills 不是孤立存在的它需要和智能体框架深度集成才能发挥最大价值。集成的关键在于框架能自动发现可用技能、根据任务动态选择技能、处理技能执行中的错误和重试、把技能结果融入对话上下文。不同的智能体框架集成方式不同。有的框架原生支持技能概念有的需要自己写适配层。选框架的时候要考虑这一点否则后期集成会很痛苦。6.3 技能开发的工程化实践技能开发要像软件开发一样工程化。版本控制、代码审查、自动化测试、持续集成、持续部署这些实践都要有。我见过不少团队把技能当成“提示词”来管理改了就改没有版本记录出了问题也不知道改了什么。这种做法的代价是系统越来越不可维护。我的建议是技能定义和实现都放在 Git 仓库里每次修改走合并请求流程自动化测试通过才能合并合并后自动部署到技能注册中心。这样整个流程可追溯、可回滚出了问题能快速定位。6.4 我个人在实际操作中的体会做了几个技能系统之后我最大的体会是技能设计的关键不在于技术实现而在于对任务的理解。一个技能好不好用取决于设计者是否真正理解这个任务在什么场景下被使用、使用者期望什么结果、可能遇到什么异常。技术实现只是把这些理解翻译成代码。另一个体会是不要追求一步到位。技能系统是演进而来的不是设计出来的。先做几个核心技能用起来发现问题再调整。我见过一些团队一开始就想设计一个完美的技能体系结果设计了好几个月还没上线最后不了了之。反而是那些先做起来再迭代的团队技能系统越用越顺手。最后分享一个小技巧给每个技能写一个“使用场景”文档用自然语言描述什么情况下该用这个技能、什么情况下不该用、常见的使用模式是什么。这个文档不参与技能定义但对团队协作特别有用。新成员加入的时候看这个文档比看代码快得多。
