企业官网建设流程全解析

1. 从“skills”这个标题说起：它到底指什么

第一次看到“skills”这个标题，很多人会以为是某个泛泛而谈的能力清单，或者一份简历上的技能罗列。但结合热搜词里的 Agent Skills、Google Cloud、GKE、Genkit 这些关键词，方向就很清楚了——这里说的 skills，是围绕 AI Agent 构建的一套可插拔能力模块体系。简单讲，就是把一个智能体需要具备的某项具体能力，封装成一个独立、可复用、可组合的单元，让 Agent 在需要的时候按需调用。

这件事解决的核心问题是：过去我们做一个 AI 应用，往往是把所有逻辑塞进一个巨大的提示词或者一条长长的调用链里，改一处动全身，复用基本靠复制粘贴。而 skills 的思路是把能力拆开，每个 skill 只干一件事，比如“读取某个数据源”“生成一份结构化报告”“调用某个外部接口做校验”，然后通过统一的调度层把它们串起来。这样做的好处是显而易见的：可测试、可替换、可组合，团队协作时边界清晰。

这套东西适合谁来参考？如果你正在做 AI Agent 相关的开发，不管是基于云端的托管服务，还是本地跑的开源框架，只要你遇到过“能力越加越多、维护越来越乱”的问题，那 skills 这套组织方式就值得认真看一遍。哪怕你只是刚接触 Agent 概念，理解 skills 的设计思路也能帮你少走很多弯路，因为它本质上是一种工程化的思维方式，而不是某个特定平台的专属功能。

我下面会从整体设计思路、核心细节、实操落地、问题排查几个层面，把 skills 这套体系拆开讲清楚。内容会结合 Google Cloud、GKE、Genkit 这些具体环境来说明，但思路本身是通用的，你换成别的技术栈也能套用。

2. 整体设计与思路拆解

2.1 为什么要把能力拆成 skill

先说一个我踩过的坑。早些年做对话式应用，所有意图识别、槽位填充、外部调用都写在一个大函数里，刚开始跑得挺顺，后来需求一多，加一个“查询订单状态”的功能，就得在几百行代码里找地方插逻辑，改完还得把所有回归用例重跑一遍。那种维护体验，做过的人都懂。

skills 这套设计的第一性原理，其实就是关注点分离。一个 skill 对应一个明确的能力边界，输入输出定义清楚，内部实现随便你怎么写，只要不破坏契约就行。这样一来，新增能力就是新增一个 skill，而不是修改一个巨型模块。测试的时候也可以单独测某个 skill，不用把整个 Agent 拉起来。

从工程角度看，这跟微服务的思路是一脉相承的，只不过粒度更细，而且运行环境往往更轻量。Agent 在运行时根据当前任务动态选择需要哪些 skill，这种“按需加载”的模式，既节省了上下文窗口，也降低了单次调用的复杂度。

2.2 方案选型：为什么是 Genkit 加 GKE 这套组合

热搜词里出现了 Google Cloud、GKE、Genkit，这不是偶然的。Genkit 是 Google 推出的一个用于构建 AI 应用的框架，它对 skill 这种能力单元有比较原生的支持，定义、注册、调用都有现成的抽象。而 GKE 作为托管的 Kubernetes 服务，解决的是部署和伸缩的问题。

为什么选这套组合？我的判断是三点。第一，Genkit 把 skill 的声明式定义做得比较干净，你不需要自己造一套注册和发现机制。第二，GKE 提供了成熟的容器编排能力，skill 可以打包成独立容器，按需扩缩容，这对流量波动大的场景很关键。第三，Google Cloud 的生态里，日志、监控、密钥管理这些配套服务比较齐全，省去了自己搭轮子的时间。

当然，这不是唯一解。如果你不想绑定特定云厂商，用开源的 Agent 框架加自建的容器平台也能实现类似效果。但如果你已经在 Google Cloud 上，那这套组合的集成成本是最低的。选型这件事没有绝对优劣，关键看你的团队熟悉什么、运维能力到什么程度。

2.3 skill 的粒度怎么把握

这是设计阶段最容易纠结的问题。粒度太粗，一个 skill 干太多事，复用性就差；粒度太细，skill 数量爆炸，调度和编排的复杂度又上来了。

我的经验是，以一个完整的、有业务意义的动作作为划分依据。比如“根据用户描述生成一份结构化的需求文档”可以是一个 skill，“把这份文档翻译成英文”可以是另一个 skill。但“提取文档里的日期”这种就不建议单独成 skill，它更适合作为前一个 skill 的内部步骤。

另一个判断标准是变更频率。如果两块逻辑经常一起改，那它们大概率应该在一个 skill 里；如果一块逻辑稳定、另一块频繁调整，那就拆开，避免频繁改动影响稳定部分。这个原则我在实际项目里反复验证过，比单纯按代码行数或者函数数量来划分靠谱得多。

3. 核心细节解析与实操要点

3.1 skill 的定义结构长什么样

一个规范的 skill 定义，通常包含这几个部分：名称、描述、输入参数 schema、输出 schema、执行逻辑。名称和描述是给调度层看的，决定了 Agent 在什么场景下会选中这个 skill。输入输出 schema 是契约，保证调用方和实现方对数据格式的理解一致。

以 Genkit 的风格为例，一个 skill 的定义大致是这样的结构：

import { defineTool } from '@genkit-ai/ai'; export const summarizeDoc = defineTool( { name: 'summarizeDoc', description: '对输入的长文本进行摘要，返回不超过指定字数的摘要内容', inputSchema: { type: 'object', properties: { content: { type: 'string', description: '待摘要的原始文本' }, maxLength: { type: 'number', description: '摘要最大字数' } }, required: ['content'] }, outputSchema: { type: 'object', properties: { summary: { type: 'string' } } } }, async (input) => { // 实际执行逻辑 const summary = await doSummarize(input.content, input.maxLength || 200); return { summary }; } );

这里有几个细节值得注意。description 写得越具体，调度层选中的准确率越高，不要写“处理文本”这种模糊描述。inputSchema 里的 required 字段要如实标注，否则调用方可能传空值进来导致运行时报错。输出 schema 尽量保持稳定，不要今天返回字符串明天返回对象，那会让下游调用方很难受。

3.2 调度层怎么决定用哪个 skill

这是整个体系里最考验设计的地方。调度层本质上是一个决策模块，它根据当前任务和上下文，从已注册的 skill 列表里选出最合适的一个或一组。

常见的做法有两种。一种是基于描述的语义匹配，把用户请求和每个 skill 的 description 做向量相似度计算，取最接近的。这种方式实现简单，但对描述质量依赖很高。另一种是基于显式路由，在提示词里明确告诉模型有哪些 skill 可用，让模型自己决定调用哪个。这种方式灵活，但需要模型有较强的指令遵循能力。

我实测下来，两者结合效果最好：先用语义匹配缩小候选范围，再把候选 skill 的详细说明交给模型做最终决策。这样既控制了提示词长度，又保留了灵活性。需要注意的是，候选数量不宜过多，一般控制在五到八个，太多了模型反而容易选错。

3.3 参数传递与类型校验的坑

skill 之间传递数据时，类型不匹配是最常见的故障来源。比如上游 skill 返回的是一个数字，下游 skill 期望的是字符串，如果不做校验，运行时就会出问题。

我的做法是在调度层加一层轻量的类型校验，调用 skill 之前先检查输入是否符合 schema，不符合就直接返回明确的错误信息，而不是让错误渗透到 skill 内部。这样排查问题时能快速定位是哪个环节的数据格式不对。

另外，可选参数的处理也要小心。如果某个参数不是必填的，skill 内部要有合理的默认值逻辑，不能假设调用方一定会传。我见过太多因为漏传可选参数导致空指针的案例，加个默认值就能避免的事，没必要等到线上出问题再补。

提示：schema 定义不要偷懒，它是你和调用方之间的合同。合同写清楚了，扯皮就少。

4. 实操过程与核心环节实现

4.1 环境准备与依赖安装

假设你已经在 Google Cloud 上有了一个项目，并且本地装好了 Node.js 环境。第一步是初始化 Genkit 相关的依赖。

mkdir agent-skills-demo && cd agent-skills-demo npm init -y npm install genkit @genkit-ai/ai @genkit-ai/google-cloud

如果你打算把 skill 部署到 GKE，还需要准备好容器相关的工具链，Docker 是必须的，kubectl 用来操作集群。这些基础工具网上教程很多，我就不展开每一步的安装了，重点说配置环节容易出问题的地方。

Genkit 初始化的时候需要指定一个模型后端，如果你用的是 Google Cloud 上的模型服务，需要配置好相应的凭据。凭据管理建议用环境变量或者密钥管理服务，不要硬编码在代码里，这是基本的安全习惯。

4.2 编写第一个可用的 skill

我们从最简单的开始，写一个“格式化日期”的 skill，虽然简单，但能完整走通定义、注册、调用的流程。

import { defineTool } from '@genkit-ai/ai'; export const formatDate = defineTool( { name: 'formatDate', description: '把时间戳转换为指定格式的日期字符串，默认格式为 YYYY-MM-DD', inputSchema: { type: 'object', properties: { timestamp: { type: 'number', description: '毫秒级时间戳' }, format: { type: 'string', description: '目标格式，可选' } }, required: ['timestamp'] }, outputSchema: { type: 'object', properties: { dateStr: { type: 'string' } } } }, async (input) => { const date = new Date(input.timestamp); const fmt = input.format || 'YYYY-MM-DD'; const dateStr = formatDateByPattern(date, fmt); return { dateStr }; } );

写完定义之后，需要在 Agent 初始化的时候把这个 skill 注册进去。注册的方式各框架略有不同，Genkit 里通常是在配置阶段把 skill 列表传进去。注册完成后，可以写一个简单的测试用例，直接调用这个 skill，确认输入输出符合预期。

4.3 把 skill 打包部署到 GKE

单个 skill 跑通之后，下一步是把它容器化并部署到 GKE。这里的关键是写好 Dockerfile，把 Node.js 运行时和你的代码一起打包进去。

FROM node:20-slim WORKDIR /app COPY package*.json ./ RUN npm ci --production COPY . . EXPOSE 8080 CMD ["node", "server.js"]

构建镜像、推送到镜像仓库、然后写 Kubernetes 的 Deployment 和 Service 配置。Deployment 里要设置好资源限制，CPU 和内存的 request 与 limit 都要给，否则调度器没法合理分配。副本数根据预期流量来定，刚开始可以设两个，观察一段时间再调整。

apiVersion: apps/v1 kind: Deployment metadata: name: skill-server spec: replicas: 2 selector: matchLabels: app: skill-server template: metadata: labels: app: skill-server spec: containers: - name: skill-server image: gcr.io/your-project/skill-server:latest ports: - containerPort: 8080 resources: requests: cpu: "250m" memory: "512Mi" limits: cpu: "500m" memory: "1Gi"

部署完成后，用 kubectl 查看 Pod 状态，确认都处于 Running。然后通过 Service 暴露的地址做一次端到端调用，验证从请求进入到 skill 执行再到返回结果的完整链路是通的。

4.4 参数计算：副本数与资源限制怎么定

这部分很多人凭感觉设，其实有简单的估算方法。假设你的 skill 平均每次调用耗时 200 毫秒，单个 Pod 能承受的并发大约是 5（取决于 CPU 限制和实际计算密度），那么单个 Pod 每秒能处理约 25 次调用。如果峰值 QPS 是 100，那至少需要 4 个副本，再留一点余量，设 5 个比较稳妥。

内存方面，Node.js 应用的基础占用加上 skill 执行时的临时对象，512Mi 到 1Gi 是比较常见的区间。如果你在 skill 里做了大文本处理或者加载了模型，那要相应上调。这些数字不是拍脑袋来的，上线后通过监控观察实际使用率，再逐步调整到合理区间。

注意：资源 limit 设得太低会导致 Pod 被 OOM Kill，设得太高又浪费资源。建议先用保守值上线，再根据监控数据优化。

5. 常见问题与排查技巧实录

5.1 skill 没有被正确调用

这是最常见的问题，表现是 Agent 该用某个 skill 的时候没用，或者用了错误的 skill。排查思路分三步。第一，检查 skill 的 description 是否足够具体，模糊的描述会让语义匹配失准。第二，确认 skill 已经正确注册，有些框架注册失败不会报错，只是静默忽略。第三，看调度层的候选列表里有没有这个 skill，如果候选阶段就被过滤掉了，那后面模型再聪明也选不到。

我遇到过一次，skill 定义完全正确，但就是调不到，最后发现是注册顺序的问题，某个前置 skill 注册失败导致后续注册被跳过。这种问题看日志最直接，注册环节一定要打日志。

5.2 输入参数类型不匹配

前面提过类型校验的重要性，这里说具体的排查方法。当 skill 报错说参数类型不对时，先看调用方传的是什么，再看 schema 定义期望的是什么。常见的情况是数字被传成了字符串，或者数组被传成了单个对象。

一个实用的技巧是在调度层加一个请求日志，把每次调用的 skill 名称和实际入参都记下来。出问题的时候直接看日志，比在代码里到处打断点快得多。日志级别可以设成 debug，生产环境平时关掉，需要排查时再开。

5.3 skill 执行超时

超时的原因通常有两类。一类是 skill 内部逻辑本身慢，比如调用了外部接口但对方响应慢，或者做了大量计算。另一类是资源不足，Pod 的 CPU 被限流了，导致执行变慢。

排查时先看监控里的 CPU 使用率，如果接近 limit，那就是资源问题，调大 limit 或者增加副本。如果 CPU 不高但就是慢，那要看 skill 内部是不是有阻塞操作。对于外部调用，一定要设超时时间，不能无限等待，否则一个慢调用会把整个链路拖垮。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑是过度依赖模型做路由。早期我完全让模型决定调用哪个 skill，结果发现模型有时候会“自作主张”组合多个 skill，产生意料之外的行为。后来改成先做规则过滤再做模型决策，稳定性好了很多。

第二个坑是skill 之间共享状态。有的 skill 需要读取前一个 skill 的输出，如果通过全局变量传递，在并发场景下会串数据。正确做法是通过参数显式传递，每个调用都是独立的。

第三个坑是忽略冷启动。GKE 上如果副本缩到零，下次请求来了要等容器启动，这段时间的延迟会很高。对于延迟敏感的场景，建议保留最小副本数，不要缩到零。

6. skill 体系的扩展与维护建议

6.1 版本管理怎么做

skill 一旦被多个 Agent 或者多个流程依赖，就不能随便改接口了。我的做法是给 skill 加版本号，接口变更时升版本，旧版本保留一段时间，等所有调用方都迁移完再下线。这样避免了“改一个 skill 崩一片”的情况。

版本号建议遵循语义化版本规范，破坏性变更升主版本，新增可选参数升次版本，内部逻辑优化升修订号。虽然听起来有点正式，但真到了多团队协作的时候，这套规范能省很多沟通成本。

6.2 监控与告警要关注哪些指标

skill 层面的监控，我重点关注四个指标：调用次数、成功率、平均耗时、错误分布。调用次数突然下降可能是调度出了问题，成功率下降说明有 skill 在报错，耗时上升可能是资源瓶颈或者外部依赖变慢，错误分布能帮你快速定位是哪个 skill 在拖后腿。

告警阈值不要设得太敏感，否则天天被误报骚扰，最后就麻木了。我一般设成连续五分钟成功率低于 95% 才告警，给一点缓冲空间。

6.3 什么时候该拆分，什么时候该合并

随着业务发展，skill 的边界可能需要调整。判断依据还是前面说的那两条：业务意义的完整性和变更频率的一致性。如果一个 skill 里有两块逻辑，一块天天改一块半年不动，那就拆开。如果两个 skill 总是被一起调用，而且它们之间数据传递很频繁，那可能合并成一个更合适。

这种调整不用追求一步到位，随着对业务理解的深入逐步优化就行。我自己的项目里，skill 的划分前后调整过三四次，每次都是因为发现了更合理的边界。

6.4 安全方面的基本考量

skill 执行时可能会接触到敏感数据，比如用户信息或者内部配置。几条基本的原则：skill 的输入输出不要记录敏感字段的明文，凭据通过密钥管理服务注入而不是写在代码或配置里，skill 的调用权限要按最小必要原则分配。

另外，如果 skill 会执行外部传入的代码或者命令，一定要做严格的校验和沙箱隔离。这个不是危言耸听，Agent 场景下输入来源复杂，多一层防护就少一分风险。

7. 我个人的一些实操体会

这套 skills 体系我用下来，最大的感受是它把“能力”这件事从模糊变成了具体。以前说“这个 Agent 能干活”，到底能干什么、干得怎么样，很难说清楚。现在每个 skill 都有明确的输入输出和测试用例，能力边界一目了然，跟产品、跟测试沟通的时候也顺畅很多。

另一个体会是，不要一开始就追求大而全。我见过有人一上来就设计几十个 skill，结果大部分都没用上，维护成本还高。正确的做法是从最核心的一两个 skill 开始，跑通流程，验证模式可行，再逐步扩展。这样每一步都有反馈，方向偏了也能及时调整。

最后分享一个小技巧：给每个 skill 写一个“使用示例”，放在描述里或者单独的文档里。调度层在做决策的时候，示例往往比抽象描述更有参考价值。这个习惯我坚持了很久，对提升调用准确率帮助很明显。

如果你也在做 Agent 相关的开发，不妨从手头最重复、最独立的那块逻辑开始，把它抽成一个 skill，感受一下这种组织方式带来的变化。很多时候，工程上的改进不需要多复杂的技术，把边界划清楚，事情就顺了一大半。