企业官网建设流程全解析

1. 从"skills"这个热词说起：它到底指什么

最近一段时间，"skills"这个词在技术社区里出现的频率明显高了起来。如果你只是偶尔刷到，可能会觉得这不就是英文里"技能"的意思吗，有什么好聊的。但真正在圈子里待过的人会发现，大家嘴里的"skills"已经变成了一个相当具体的概念——它指的是围绕智能体（Agent）构建的一套可插拔能力模块，有时候也叫 Agent Skills。简单说，就是给一个通用的大模型智能体装上一个个"技能包"，让它从"什么都能聊两句"变成"某件事真的能干"。

我最早接触这个概念，是在折腾 Google Cloud 上的一套智能体方案时。当时的需求很朴素：想让一个智能体既能查数据库，又能调外部接口，还能按固定格式生成报告。如果把这些逻辑全塞进一个巨大的提示词里，维护起来简直是灾难——改一处牵动全身，测试也没法单独测。后来接触到 Agent Skills 的思路，才意识到正确的做法应该是把这些能力拆成独立的、可复用的模块，每个模块只负责一件事，需要的时候挂上去，不需要就摘下来。这个思路一打通，整个项目的可维护性上了一个台阶。

所以这篇内容我想聊的，不是空泛地解释"什么是 skills"，而是把我自己在实际项目里踩过的坑、总结出来的方法完整地摊开。核心会围绕几个关键词展开：Agent Skills 的模块化设计、在 GKE 上的部署与调度、用 Genkit 做技能编排，以及技能测试与调试的实操经验。适合的读者是那些已经用过大模型 API、想进一步把智能体做成真正可用产品的开发者，也适合刚听说 skills 这个词、想搞清楚它和普通函数调用有什么区别的朋友。我会尽量用大白话把原理讲透，同时给出可以直接抄的配置和步骤。

需要先说明一点：skills 这个概念目前在不同平台、不同框架下的具体实现差异挺大，有的把它做成配置文件，有的做成代码插件，有的干脆就是一段结构化的提示词模板。我下面讲的主要是基于我实际用过的、以 Google Cloud 生态为主的一套实践，但里面的设计思路是通用的，你换成别的框架也能借鉴。

2. Agent Skills 的本质：为什么不是简单的函数调用

2.1 从"一个大提示词"到"一堆小技能"的思维转变

很多人第一次做智能体，习惯把所有的能力都写进系统提示词里。比如"你是一个助手，你可以查天气、可以算数、可以翻译、可以总结文档……"然后下面跟一大段说明。这种做法在能力少的时候还能凑合，一旦超过五六个功能，问题就全冒出来了。首先是提示词长度爆炸，每次请求都要带上全部说明，token 成本高得离谱；其次是功能之间会互相干扰，模型经常搞混该用哪个能力；最后是没法单独测试，你改了一个功能的描述，可能把另一个功能搞坏了都不知道。

Agent Skills 的核心思路就是解耦。每个技能是一个独立的单元，有自己的名称、描述、输入输出定义，以及具体的执行逻辑。智能体在运行时，先根据用户意图判断需要哪个技能，然后只加载那个技能的相关信息。这就像你去餐厅点菜，服务员不需要把整本菜单背下来，只需要知道"客人要的是川菜"，然后把川菜师傅叫出来就行。这个类比可能不太严谨，但意思到位了：按需加载、职责单一、独立可测，这三点是 skills 设计的基本原则。

我自己的项目里，最开始是把"查询订单状态"和"修改收货地址"两个功能放在同一个技能里，因为它们都属于订单管理。结果测试时发现，模型经常在用户只是想查状态的时候，误触发地址修改的逻辑。后来拆成两个独立技能，各自有清晰的触发条件描述，误触发率立刻降下来了。这个教训让我明白，技能的粒度划分不能按业务领域来，而要按"用户意图"来。

2.2 技能描述的质量直接决定调用准确率

拆成独立技能只是第一步，真正决定智能体能不能正确调用技能的，是技能描述写得好不好。这里有个反直觉的点：技能描述不是写给人类看的文档，而是写给模型看的"触发条件"。所以它要足够具体，包含用户可能用的各种说法。

举个例子，一个"查询天气"的技能，如果描述只写"查询天气"，那用户说"明天出门要不要带伞"的时候，模型可能就反应不过来。更好的描述应该写成"当用户询问某地某时的天气状况、温度、降水概率，或者询问出行是否需要带伞、穿什么衣服时使用此技能"。你看，这就把各种隐含意图都覆盖进去了。

我在实际项目里总结了一个写技能描述的模板，基本能覆盖大部分场景：

• 触发场景：用户在什么情况下会需要这个技能，尽量列举同义表达
• 不触发场景：什么情况下绝对不要用这个技能，用来排除干扰
• 输入要求：需要用户提供哪些信息，缺了要主动追问
• 输出格式：返回结果长什么样，方便下游处理

这个模板看起来简单，但"不触发场景"这一条是很多人会忽略的。加上它之后，技能之间的边界清晰了很多，模型也不会动不动就"越界"。

2.3 技能与工具调用的区别在哪里

有人会问，这不就是 function calling 吗，换个名字而已？我的理解是，function calling 是底层机制，skills 是上层封装。function calling 解决的是"模型如何输出一个结构化的调用请求"，而 skills 解决的是"如何组织、管理、复用这些调用能力"。

打个比方，function calling 像是电路板上的引脚，skills 像是插在引脚上的一个个模块。引脚本身不关心你插的是什么，但模块有自己的规格、有自己的说明书、有自己的测试用例。一个成熟的 skills 体系，应该包含技能的注册、发现、版本管理、权限控制、执行监控等一整套东西，而不只是几个函数定义。

这也是为什么现在很多平台都在推自己的 skills 规范。因为一旦技能多了，没有统一的管理机制，就会变成一团乱麻。我在 GKE 上部署的时候，就专门做了一层技能注册中心，所有技能启动时向中心注册自己的元信息，智能体运行时从中心拉取可用技能列表。这样一来，新增技能不需要改智能体的代码，只要注册上去就能被发现。

3. 在 GKE 上落地 Agent Skills 的完整链路

3.1 为什么选 GKE 而不是简单的函数计算

先说选型理由。做智能体技能，最省事的做法可能是用函数计算，一个技能一个函数，按调用付费。我一开始也是这么干的，但很快就遇到了瓶颈。函数计算适合无状态的短任务，但很多技能需要维护状态，比如会话上下文、缓存、连接池。而且技能之间有时候需要互相调用，函数计算之间的通信延迟和冷启动问题很烦人。

GKE 的好处是，你可以把技能做成常驻的服务，每个技能是一个独立的 Pod，有自己的资源配额、自己的健康检查、自己的日志。技能之间通过服务发现互相调用，延迟低且稳定。更重要的是，GKE 的自动扩缩容可以按每个技能的负载独立调整，热门技能多给几个副本，冷门技能保持最小实例就行，成本控制得很精细。

当然，GKE 的复杂度也比函数计算高不少。如果你只是做个小 demo，没必要上 GKE。但如果你要做的是一个要长期运行、技能数量会不断增长的智能体平台，那 GKE 的这套基础设施是值得投入的。

3.2 技能容器的标准化封装

在 GKE 上跑技能，第一步是把每个技能封装成标准容器。我定的规范是这样的：每个技能镜像必须暴露一个 HTTP 接口，接收 POST 请求，请求体是 JSON 格式，包含skill_name、input、context三个字段。返回也是 JSON，包含status、output、error三个字段。

这个规范看起来简单，但统一之后好处巨大。智能体侧不需要知道每个技能内部怎么实现的，只要按统一格式调用就行。新增技能只要符合这个规范，就能无缝接入。

下面是一个技能容器的 Dockerfile 示例，用的是 Python：

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"]

对应的技能服务主文件大概长这样：

from fastapi import FastAPI from pydantic import BaseModel app = FastAPI() class SkillRequest(BaseModel): skill_name: str input: dict context: dict = {} class SkillResponse(BaseModel): status: str output: dict = {} error: str = "" @app.post("/invoke") async def invoke(req: SkillRequest): try: result = handle_skill(req.skill_name, req.input, req.context) return SkillResponse(status="ok", output=result) except Exception as e: return SkillResponse(status="error", error=str(e))

这个骨架你直接拿去改就行。关键是handle_skill这个函数，里面根据skill_name分发到具体的处理逻辑。我建议每个技能单独一个文件，然后在handle_skill里做路由，这样代码清晰，也方便单独测试。

3.3 技能注册与发现的实现细节

技能容器跑起来之后，怎么让智能体知道有哪些技能可用？我的做法是在 GKE 里单独部署一个技能注册中心，所有技能 Pod 启动时向它注册。注册中心维护一个技能清单，包含技能名称、描述、调用地址、健康状态。

注册的时机很关键。我一开始是在容器启动脚本里直接发注册请求，结果发现如果注册中心还没起来，技能就注册失败了。后来改成用 Kubernetes 的 readiness probe 配合一个初始化容器，等注册中心可用之后再注册。更稳妥的做法是用一个 sidecar 容器专门负责注册和心跳，主容器只管业务逻辑。

技能清单的数据结构大概是这样：

智能体在规划任务时，先拉取这个清单，把技能名称和描述拼进提示词，让模型选择。选定之后，再根据 endpoint 发起实际调用。这个两阶段的设计，把"选择"和"执行"分开了，调试起来方便很多——你可以单独看模型选得对不对，再看执行结果对不对。

3.4 用 Genkit 做技能编排的实践

Genkit 是 Google 出的一个智能体开发框架，我用它来做技能编排。它的核心概念是 flow，一个 flow 就是一条完整的处理链路，里面可以包含多个步骤，每个步骤可以是模型调用、技能调用、或者普通的数据处理。

用 Genkit 编排技能的好处是，它把技能调用抽象成了 flow 里的一个节点，你可以在节点之间做条件判断、循环、错误处理。比如一个"订机票"的 flow，可能是这样的：先调用"查询航班"技能，然后根据结果调用"比价"技能，最后调用"下单"技能。如果中间任何一步失败，flow 可以走降级逻辑。

下面是一个简化的 Genkit flow 示例：

import { genkit } from 'genkit'; import { googleAI } from '@genkit-ai/googleai'; const ai = genkit({ plugins: [googleAI()] }); export const bookFlightFlow = ai.defineFlow( { name: 'bookFlight', inputSchema: z.object({ from: z.string(), to: z.string(), date: z.string() }), outputSchema: z.object({ orderId: z.string(), price: z.number() }), }, async (input) => { const flights = await callSkill('query_flights', input); const best = await callSkill('compare_price', { flights }); const order = await callSkill('place_order', { flight: best }); return order; } );

这里的callSkill是我自己封装的函数，内部就是按前面说的统一格式发 HTTP 请求。Genkit 负责的是流程控制、状态传递、错误重试这些脏活。实测下来，用 Genkit 编排比手写状态机要省心得多，尤其是流程复杂的时候。

4. 技能测试：比写技能更花时间的环节

4.1 为什么技能测试不能只测代码逻辑

技能测试和普通单元测试最大的区别在于，你要测的不只是代码逻辑对不对，还要测模型会不会在正确的时机调用它。这两件事的测试方法完全不同。代码逻辑可以用传统的单元测试覆盖，但"调用时机"的测试，需要构造大量的用户输入样本，看模型的选择是否符合预期。

我在项目里专门建了一个测试集，每个技能对应一组测试用例，每个用例包含一段用户输入和期望调用的技能名称。跑测试的时候，把用户输入喂给智能体，看它实际调用了哪个技能，和期望对比。这个测试集的维护成本不低，但非常值得，因为它能捕捉到提示词改动带来的回归问题。

测试用例的格式大概是这样：

{ "input": "明天北京会下雨吗", "expected_skill": "query_weather", "expected_params": {"city": "北京", "date": "明天"} }

跑一轮测试下来，如果某个技能的准确率低于阈值，就说明它的描述需要调整。我一般把阈值定在 90%，低于这个数就得回去改描述。

4.2 技能之间的干扰测试怎么做

单个技能测准了，不代表组合起来就没问题。技能之间会互相干扰，尤其是描述有重叠的时候。比如"查询订单"和"查询物流"两个技能，用户说"我的包裹到哪了"，到底该调哪个？这种边界情况必须专门测。

我的做法是构造一批"模糊输入"，这些输入故意不明确指向某个技能，然后看模型的选择是否合理。如果模型选错了，说明两个技能的描述边界需要重新划分。有时候解决方法是给其中一个技能加上"不触发场景"，明确排除掉另一个技能的领域。

还有一种干扰是"级联触发"，就是模型调了一个技能之后，又自动调了另一个不该调的技能。这种情况通常是因为技能的输出格式让模型产生了误解。解决办法是在技能返回结果里加上明确的"下一步建议"字段，告诉模型接下来该干什么、不该干什么。

4.3 用真实流量做灰度验证

测试集再全，也覆盖不了真实用户的各种奇葩说法。所以技能上线前，我都会做一轮灰度验证：把新技能只开放给一小部分流量，同时记录所有调用日志，人工抽查一批看有没有问题。

灰度期间重点看几个指标：调用量是否符合预期、错误率、平均响应时间、以及"该调没调"和"不该调却调了"的比例。这几个指标如果都正常，再逐步放大流量。我吃过一次亏，一个新技能没做灰度直接全量上线，结果它的描述和另一个老技能太像，导致老技能的调用量骤降，用户投诉了好几天才发现。

5. 那些文档里不会写的踩坑经验

5.1 技能描述里的"隐藏陷阱"

写技能描述有几个坑，我一个个说。第一个坑是用了太多专业术语。比如你写"使用此技能进行实体识别"，模型可能不知道"实体识别"具体指什么场景。改成"当用户提到人名、地名、公司名、时间、金额等具体信息，需要从中提取出来时使用此技能"，效果就好很多。

第二个坑是描述太长。有人觉得描述越详细越好，结果写了五百字，反而让模型抓不住重点。我的经验是，核心触发条件放在最前面，用一两句话讲清楚，补充说明放在后面。模型对开头的内容更敏感。

第三个坑是多个技能描述用了相同的开头。比如好几个技能都以"当用户询问……"开头，模型就容易混淆。解决办法是让每个技能的开头有辨识度，比如用不同的动词、不同的场景词。

5.2 技能超时与重试的坑

技能调用超时是家常便饭，尤其是调用外部接口的技能。我一开始没做超时控制，结果一个慢技能把整个智能体的响应拖垮了。后来给每个技能调用都加了超时，默认 5 秒，外部接口类的技能放宽到 15 秒。

重试也要小心。不是所有技能都适合重试。查询类的技能重试没问题，但下单、支付类的技能绝对不能盲目重试，否则会重复下单。我的做法是在技能元信息里加一个idempotent字段，标记这个技能是否幂等，只有幂等的技能才允许自动重试。

还有一个坑是重试时的参数问题。如果第一次调用因为参数错误失败，重试同样的参数还是会失败。所以重试之前要先判断错误类型，参数错误直接返回给用户，不要重试。

5.3 技能版本管理的重要性

技能是会迭代的，今天 v1 明天 v2。如果没有版本管理，新旧技能混在一起，问题很难排查。我的做法是每个技能镜像都打上版本标签，注册中心里同时保留多个版本，智能体调用时指定版本。这样新版本可以灰度，出问题可以快速回滚到旧版本。

版本管理还有一个好处是，可以做 A/B 测试。同一个技能的两个版本同时在线，各分一半流量，对比调用准确率和用户满意度，用数据决定留哪个。

5.4 日志与可观测性

技能多了之后，没有好的日志系统根本没法排查问题。我的做法是每个技能调用都记录一条结构化日志，包含请求 ID、技能名称、输入参数、输出结果、耗时、错误信息。这些日志汇总到一个中心化的日志系统里，可以按请求 ID 串联起整个调用链路。

有了这套日志，排查问题就快多了。用户反馈"智能体答非所问"，我只要拿到请求 ID，就能看到模型当时选了哪个技能、传了什么参数、技能返回了什么，问题出在哪一环一目了然。

6. 技能生态的扩展思路

6.1 从自建技能到复用社区技能

自己写技能写到一定数量，就会开始想能不能复用别人的。现在确实有一些社区在分享技能包，但直接拿来用要谨慎。因为技能描述是和你的智能体提示词强相关的，别人的描述风格未必适合你。我的做法是，社区技能拿来之后，先跑一遍自己的测试集，看准确率如何，不达标就改描述，改到符合自己的场景为止。

复用的时候还要注意依赖问题。一个社区技能可能依赖特定的外部服务或特定的库版本，直接集成进来可能和现有环境冲突。所以最好把社区技能当成参考，理解它的设计思路，然后自己重新实现一遍，这样可控性更强。

6.2 技能的权限与安全边界

技能能调外部接口，就意味着有安全风险。一个设计不当的技能，可能被诱导去调用不该调的接口，或者泄露敏感信息。我的做法是给每个技能设定明确的权限边界，比如"只能读不能写"、"只能访问特定域名"、"输入参数必须经过校验"。

还有一个容易忽略的点是技能的输入校验。模型生成的参数不一定符合预期，可能包含注入攻击的 payload。所以技能内部一定要做严格的输入校验，不能信任模型传来的任何东西。这一点我在早期项目里吃过亏，一个技能直接把模型传来的 SQL 片段拼进了查询语句，幸好测试环境发现了，不然后果严重。

6.3 技能性能优化的几个方向

技能多了之后，性能会成为瓶颈。优化的方向有几个。第一是缓存，对于查询类技能，相同参数的请求可以缓存结果，减少重复计算。第二是并行，如果多个技能之间没有依赖关系，可以并行调用，缩短总耗时。第三是预热，对于冷启动慢的技能，保持最小实例数，避免每次调用都要等启动。

我在 GKE 上做性能优化时，给每个技能配置了 HPA（水平 Pod 自动扩缩），根据 CPU 和自定义指标（比如队列长度）自动调整副本数。同时给技能容器设置了合理的资源请求和限制，避免一个技能吃光节点资源影响其他技能。

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

折腾 skills 这套东西有一段时间了，最大的体会是：技能设计的好坏，八成取决于描述写得好不好，两成取决于代码实现。很多人把精力都花在写代码上，觉得描述随便写写就行，结果模型调用准确率上不去，回头还得返工。我的建议是，写技能描述的时间至少要和写代码的时间一样多，甚至更多。

另一个体会是，不要一开始就追求大而全的技能体系。我见过有人一上来就规划了几十个技能，结果每个都做得半吊子。正确的做法是先做三五个核心技能，把注册、发现、调用、测试、监控这一整套链路跑通，验证没问题了，再逐步增加技能。基础设施比技能数量重要得多。

还有一点是关于测试的投入。技能测试集的维护确实费时间，但它是保证质量的唯一手段。我现在的习惯是，每新增一个技能，必须同时提交对应的测试用例，没有测试用例的技能不允许上线。这个规矩看起来严格，但省去了后面无数的救火时间。

最后分享一个小技巧：给技能起名的时候，用动词开头，比如query_、create_、update_、delete_，这样一眼就能看出技能是干什么的，也方便按前缀做权限控制。这个习惯是从 RESTful API 设计里借鉴来的，用在技能命名上同样好使。