企业官网建设流程全解析

1. 从"skills"这个词说起：为什么它突然成了AI工程圈的热词

如果你最近在AI工程社区里泡着，大概率会频繁撞见"skills"这个词。它不再只是招聘JD里"要求具备良好的沟通skills"那种泛泛而谈，而是变成了一个具体的技术实体——Agent Skills。简单说，它是给AI Agent（智能体）装配的一套可复用、可组合、可版本化的能力模块。你可以把它理解成给一个刚入职的聪明实习生发了一本《岗位操作手册》，手册里每一页写清楚"遇到X情况，按Y步骤调用Z工具"，而这个实习生就是你的Agent。

这件事为什么值得单独拿出来聊？因为过去一年里，大家做AI应用最大的痛点不是模型不够聪明，而是模型聪明但不可控、不可复用、不可测试。你写一个能查数据库、能发邮件、能生成报表的Agent，换一个业务场景就得从头再写一遍提示词和工具调用逻辑，维护成本高得离谱。Agent Skills要解决的就是这个问题：把"能力"从"提示词"里剥离出来，变成独立的一等公民。

这篇文章适合谁看？如果你正在用Google Cloud上的AI/ML服务做Agent开发，或者你在用Genkit这类框架搭建生成式AI应用，又或者你只是好奇"claude agent skills: a first principles deep dive"这类讨论到底在讲什么，那这篇内容能帮你把概念、原理、落地路径和踩坑经验一次性理清楚。我会尽量用从业者之间聊天的口吻，把这件事从"听起来很玄"讲到"我明天就能动手试"。

2. Agent Skills到底是什么：把能力从提示词里解放出来

2.1 一个生活化类比：Skills就像给员工发的"标准作业程序"

想象你开了一家餐厅，后厨有个很聪明的厨师。你不告诉他怎么做菜，他也能凭感觉炒出东西，但每次味道都不一样，而且换个厨师就完全崩了。于是你写了一份SOP（标准作业程序）："宫保鸡丁：热油→下花椒→下鸡丁→加料汁→收汁"。这份SOP就是Skill。

Agent Skills的逻辑一模一样。一个Skill通常包含几个要素：名称与描述（告诉Agent这个能力是干什么的）、输入输出契约（需要什么参数、返回什么结构）、执行逻辑（调用哪个API、走什么流程）、边界条件（什么情况下不该用这个Skill）。当Agent接到用户请求时，它不再需要从零推理"我该怎么做"，而是先检索有哪些可用Skills，然后按契约调用。

这个转变的意义在于：提示词工程从"写作文"变成了"搭积木"。以前你调一个Agent，可能要写两千字的系统提示词，把各种规则、示例、边界都塞进去，改一个地方就牵一发动全身。现在你把每个能力拆成独立Skill，主提示词只需要说"你是一个助手，根据任务选择合适的Skill执行"，剩下的交给Skill自己描述。

2.2 和传统Function Calling的区别在哪

有人会问：这不就是Function Calling吗？OpenAI、Anthropic早就支持了。确实有重叠，但Agent Skills在几个维度上走得更远。

第一，Function Calling是单次调用，Skills是有状态的流程。一个Function Call通常是"给我参数，我返回结果"，一次交互结束。而一个Skill可以包含多步操作、条件分支、甚至调用其他Skill。比如"生成月度销售报告"这个Skill，内部可能先调用"查询数据库"Skill，再调用"数据清洗"Skill，最后调用"生成图表"Skill。

第二，Function Calling绑定在模型API上，Skills是框架层的抽象。你在Genkit里定义一个Skill，理论上可以挂到不同的模型后端上，换模型不用重写能力层。这在多模型混用的生产环境里非常关键。

第三，Skills强调可发现性和可组合性。Agent需要知道"我有哪些能力可用"，这要求Skills有统一的注册、检索、版本管理机制。Function Calling本身不解决这个问题，你得自己搭一套。

2.3 为什么Google Cloud和Genkit在这个话题里频繁出现

Google Cloud在这件事上的布局比较系统。它的Vertex AI Agent Builder提供了一套Agent编排能力，而Genkit是面向开发者的开源框架，专门用来构建AI驱动的应用。Genkit里对"工具"和"流程"的抽象，天然适合承载Agent Skills的概念。

具体来说，Genkit的tool定义让你用TypeScript或Go声明一个能力，包含Zod schema描述的输入输出，然后flow把这些能力串起来。你可以在本地用Genkit的开发者UI调试每个Skill的调用链路，观察输入输出，这在排查"Agent为什么调错了Skill"时特别有用。而部署到Cloud Run或GKE之后，这些Skills就变成了可水平扩展的服务。

热搜词里出现GKE（Google Kubernetes Engine）不是偶然的。当你的Agent Skills数量上去之后，你需要一个稳定的运行时来托管它们，需要服务发现、需要自动扩缩容、需要可观测性。GKE提供的正是这套基础设施。所以"Agent Skills + Google Cloud + GKE + Genkit"这条链路，实际上是从能力定义到生产部署的完整路径。

3. 拆解一个Skill的内部结构：从契约到执行

3.1 输入输出契约：为什么Schema比提示词更可靠

一个Skill最核心的部分不是它的执行代码，而是它的契约。契约定义了"这个Skill接受什么、返回什么"。在Genkit里，你用Zod来写这个契约，比如一个"查询订单"的Skill：

import { z } from "genkit"; const OrderQueryInput = z.object({ orderId: z.string().describe("订单编号，格式为ORD-开头"), includeItems: z.boolean().default(true).describe("是否返回订单明细"), }); const OrderQueryOutput = z.object({ status: z.enum(["pending", "shipped", "delivered", "cancelled"]), items: z.array(z.object({ sku: z.string(), quantity: z.number(), })).optional(), updatedAt: z.string(), });

为什么用Schema而不是在提示词里写"请返回订单状态和明细"？因为Schema是机器可验证的。当模型生成的参数不符合Schema时，框架可以直接拦截并让模型重试，而不是等到执行阶段才发现参数错了。这在实际生产里能省掉大量调试时间。我踩过的坑是：早期用纯提示词描述输入格式，模型十次里有两次会把订单号写成"订单号：ORD-123"这种带前缀的格式，导致查询失败。换成Schema约束后，这类问题基本消失。

3.2 执行逻辑：同步、异步还是流式

Skill的执行逻辑有三种常见形态，选择哪种取决于你的场景。

同步执行适合快速返回的能力，比如"计算税费"、"格式化日期"。这类Skill通常在几十毫秒内完成，直接返回结果即可。

异步执行适合耗时操作，比如"生成一份PDF报告"、"调用外部API拉取数据"。这时候Skill应该返回一个任务ID，让Agent轮询或者通过回调通知。Genkit里可以用flow的异步能力来处理。

流式执行适合需要逐步输出给用户的场景，比如"实时翻译"、"逐字生成摘要"。流式Skill的契约里输出是一个流对象，而不是单个结果。

选择哪种形态的判断标准很简单：用户能等多久。超过3秒的操作，建议走异步；需要用户看到中间过程的，走流式；其余走同步。这个阈值不是拍脑袋来的，是根据人机交互研究里"3秒注意力窗口"的经验值。

3.3 边界条件：Skill的"不该用"比"怎么用"更重要

这是最容易被忽略但最影响Agent表现的部分。一个Skill如果只写"我能做什么"，不写"我什么时候不该被调用"，Agent就会滥用它。比如你有一个"发送邮件"Skill，如果不加边界，Agent可能在用户只是问"邮件模板怎么写"的时候就直接发邮件了。

边界条件通常包括：前置条件（比如"只有当订单状态为shipped时才能调用物流查询"）、互斥条件（比如"这个Skill和另一个Skill不能同时调用"）、失败降级（比如"如果外部API超时，返回缓存数据并标记为stale"）。在Genkit里，你可以在Skill的描述字段里写清楚这些，模型在规划时会参考描述来决定是否调用。

我的经验是：边界条件的描述要具体到可判断。写"适用于查询场景"没用，写"当用户提供了订单号且询问订单状态时使用"才有用。模型不是人，它需要明确的触发信号。

4. 在Genkit里落地Agent Skills：完整实操流程

4.1 环境准备与项目初始化

先把基础环境搭起来。你需要Node.js 20以上、npm或pnpm，以及一个Google Cloud项目（如果要部署到Cloud Run或GKE）。本地开发阶段其实不需要云资源，Genkit有本地开发者UI可以跑通全流程。

npm install -g genkit-cli mkdir agent-skills-demo && cd agent-skills-demo npm init -y npm install genkit @genkit-ai/googleai zod

初始化之后，创建一个src/skills目录专门放Skill定义，一个src/flows目录放编排逻辑。这个目录结构不是强制的，但分开之后维护起来清晰很多。我见过把所有东西塞一个文件里的项目，Skill超过五个之后基本没法看。

4.2 定义第一个Skill：从"查询天气"开始

用一个简单例子把流程跑通。假设我们要做一个"出行建议"Agent，第一个Skill是查询天气。

import { genkit, z } from "genkit"; import { googleAI } from "@genkit-ai/googleai"; const ai = genkit({ plugins: [googleAI()] }); export const getWeather = ai.defineTool( { name: "getWeather", description: "查询指定城市当前天气。当用户询问天气、出行建议且提供了城市名时使用。", inputSchema: z.object({ city: z.string().describe("城市名称，中文或英文均可"), unit: z.enum(["celsius", "fahrenheit"]).default("celsius"), }), outputSchema: z.object({ city: z.string(), temperature: z.number(), condition: z.string(), suggestion: z.string(), }), }, async (input) => { // 实际项目里这里调用天气API const mockData = { city: input.city, temperature: input.unit === "celsius" ? 22 : 72, condition: "多云", suggestion: "适合外出，建议带一件薄外套", }; return mockData; } );

注意description里我写了"当用户询问天气、出行建议且提供了城市名时使用"。这就是边界条件的体现。如果你只写"查询天气"，模型可能在用户说"今天心情像天气一样阴"的时候也去调用它。

4.3 把Skills编排成Flow：让Agent自己选能力

定义好Skill之后，用ai.generate把Skills挂上去，让模型自主决定调用哪个。

import { getWeather } from "./skills/weather"; export const travelAdvisor = ai.defineFlow( { name: "travelAdvisor", inputSchema: z.object({ query: z.string() }), outputSchema: z.string(), }, async (input) => { const response = await ai.generate({ model: googleAI.model("gemini-2.0-flash"), prompt: input.query, tools: [getWeather], system: "你是一个出行建议助手。根据用户问题，选择合适的工具获取信息，然后给出建议。如果不需要工具，直接回答。", }); return response.text; } );

跑起来之后，用genkit start启动开发者UI，你可以在浏览器里输入"我明天去杭州，需要带伞吗"，观察Agent是否调用了getWeather，传入了什么参数，返回了什么结果。这个可视化调试能力是Genkit相比裸写API最大的优势之一。

4.4 参数选择与性能权衡

在实际项目里，有几个参数需要你根据场景调。

模型选择：Gemini 2.0 Flash适合大多数Skill调用场景，速度快、成本低。如果Skill的规划逻辑特别复杂（比如需要多步推理才能决定调用顺序），可以换Pro版本，但延迟会明显上升。我的经验是先用Flash跑，遇到规划错误率超过10%再考虑升级。

工具调用模式：Genkit支持让模型"自动选择工具"或"强制调用某个工具"。自动模式灵活但可能漏调，强制模式可控但失去灵活性。生产环境里我倾向于自动模式加上明确的系统提示词约束。

超时设置：每个Skill应该有独立的超时。查询类Skill设3秒，生成类设30秒，超过就降级。不要用一个全局超时，否则要么查得太慢被砍，要么生成类被误杀。

5. 从本地到生产：部署到Cloud Run与GKE的路径

5.1 什么时候该上GKE，什么时候Cloud Run就够了

这是很多人纠结的问题。我的判断标准是看Skills的数量和调用模式。

如果你的Agent只有几个Skill，流量是突发性的，Cloud Run是最省事的选择。它按请求计费，冷启动虽然有几秒但可以接受，而且部署就是一条命令。Genkit官方也提供了Cloud Run的部署模板。

但如果你的Skills超过二十个，或者有多个Agent共享同一批Skills，或者你需要Skill之间通过内部网络低延迟通信，那就该考虑GKE了。GKE的优势在于：你可以把每个Skill或每组Skill部署成独立的Deployment，用Service做服务发现，用HPA做自动扩缩容，用Istio或Anthos Service Mesh做流量管理。当某个Skill被高频调用时，它可以独立扩容，不影响其他Skill。

热搜词里GKE和Agent Skills绑在一起，反映的正是这个趋势：Skills从"代码里的函数"变成"集群里的服务"。

5.2 容器化一个Skill服务

把Genkit应用打包成容器，Dockerfile大概长这样：

FROM node:20-slim WORKDIR /app COPY package*.json ./ RUN npm ci --only=production COPY . . RUN npm run build EXPOSE 3400 CMD ["node", "lib/index.js"]

构建之后推到Artifact Registry，然后部署到Cloud Run：

gcloud run deploy agent-skills \ --source . \ --region asia-east1 \ --allow-unauthenticated \ --set-env-vars GOOGLE_CLOUD_PROJECT=your-project-id

如果走GKE，流程是：构建镜像→推送到Artifact Registry→写Deployment和Service的YAML→kubectl apply。GKE这边我建议至少配一个HorizontalPodAutoscaler，基于CPU或自定义指标（比如Skill调用队列长度）来扩缩。

5.3 可观测性：怎么知道Skill调对了没有

生产环境里最怕的不是Skill报错，而是Skill"静默地调错了"。用户问A，Agent调了B，返回了一个看起来合理但实际无关的结果。这种问题在日志里很难发现，因为没有任何异常。

解决方案是结构化日志加调用链追踪。每个Skill调用时记录：trace_id、skill_name、input、output、latency、model_used。然后在Cloud Logging里建仪表盘，观察每个Skill的调用频率和成功率。如果某个Skill的调用频率突然飙升，可能是模型在滥用它；如果某个Skill的成功率下降，可能是外部依赖出了问题。

Genkit本身有OpenTelemetry集成，可以导出trace到Cloud Trace。这个在排查"为什么这次调用慢了3秒"的时候特别有用，你能看到时间花在模型推理上还是Skill执行上。

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

6.1 Agent不调用Skill，或者调用了错误的Skill

这是最高频的问题。排查顺序是这样的：

先看Skill的description是否足够明确。模型选择Skill主要靠描述匹配，如果描述太泛（比如"处理数据"），模型就不知道该不该用。改成"当用户提供了CSV文件路径且要求统计行数时使用"这种具体描述，命中率会大幅提升。

再看系统提示词是否给了足够的规划空间。有些系统提示词写得太死，比如"你必须先调用工具再回答"，导致模型在不需要工具的场景也硬调。改成"根据问题需要决定是否使用工具"更合理。

最后看模型能力。如果用的是小模型，规划能力确实有限。可以试试在系统提示词里加一两个few-shot示例，展示"什么问题该调什么Skill"，通常能显著改善。

6.2 Skill执行超时或返回格式错误

超时问题通常出在外部依赖上。我的做法是给每个Skill加熔断和降级：连续失败三次就暂时禁用这个Skill，返回一个默认值或提示用户稍后再试。不要让一个坏掉的Skill拖垮整个Agent。

格式错误多半是契约没写严。检查你的Zod schema是否用了.strict()，是否对字符串长度、数字范围做了约束。模型有时候会返回"temperature: '22'"这种字符串形式的数字，如果schema是z.number()就会失败。可以在schema里用z.coerce.number()做自动转换，但更好的做法是让模型重试。

6.3 多个Skill之间的依赖和冲突

当Skills多起来之后，会出现"Skill A的输出是Skill B的输入"这种依赖链。Genkit的flow可以处理这个，但要注意循环依赖。我见过一个案例：Skill A调用Skill B，Skill B在某些条件下又调用Skill A，导致无限递归。解决办法是在Skill的边界条件里明确"不调用哪些Skill"，或者在flow层面加调用深度限制。

冲突则常见于两个Skill功能重叠。比如同时有"查询用户"和"查询客户"两个Skill，模型可能随机选一个。这时候要么合并成一个Skill用参数区分，要么在描述里写清楚适用场景的差异。

6.4 常见问题速查表

6.5 几个我踩过的坑

第一个坑是在Skill里做太多事。早期我把"查询订单+计算折扣+生成发票"塞进一个Skill，结果调试时根本不知道是哪一步出了问题。后来拆成三个独立Skill，每个只做一件事，问题定位时间从半小时降到两分钟。Skill的粒度应该以"能否独立测试"为标准。

第二个坑是忽略Skill的版本管理。生产环境里改了一个Skill的逻辑，结果依赖它的Agent行为全变了。后来我们给每个Skill加版本号，Agent调用时指定版本，新版本先在小流量上验证再全量。这个在GKE里可以通过不同的Deployment tag来实现。

第三个坑是没有给Skill设成本上限。有个Skill会调用一个按次计费的外部API，某天模型抽风疯狂调用，一天烧掉了几百块。后来加了每小时的调用次数上限，超过就降级到缓存数据。这个教训是：任何有外部成本的Skill都必须有配额控制。

7. 关于Agent Skills测试的一些实战心得

热搜词里"agent skills测试"是个很实在的话题。Skills的测试和普通函数测试不一样，因为它的调用决策是模型做的，有不确定性。我的做法是分三层测。

第一层是Skill本身的单元测试。给定输入，验证输出符合schema，验证异常处理正确。这层用常规测试框架就行，不涉及模型。

第二层是Skill选择的集成测试。准备一批"用户问题→期望调用的Skill"的样本，跑一遍看命中率。命中率低于90%就要调整描述或系统提示词。这批样本要覆盖边界情况，比如"模糊问题"、"多意图问题"、"不需要Skill的问题"。

第三层是端到端的行为测试。模拟真实对话，看Agent在多轮交互中是否能正确组合Skills。这层最难自动化，通常需要人工评估或者用另一个模型做裁判。我的经验是维护一个"回归测试集"，每次改Skill描述或系统提示词都跑一遍，防止改A坏B。

测试环境要和生产环境隔离，但Skill的定义要同步。我见过测试环境和生产环境的Skill描述不一致导致行为差异的情况，排查了很久才发现是配置漂移。现在我们的做法是Skill定义走代码仓库，测试和生产用同一份代码，只是环境变量不同。

8. 这套东西后续还能怎么扩展

Agent Skills这个概念还在快速演进。我观察到几个方向值得关注。

一个是Skills的市场化。现在已经有人在讨论"Skill Registry"的概念，就像npm之于JavaScript，未来可能出现一个公共的Skill仓库，开发者可以发布和订阅Skill。Google Cloud的Vertex AI Extensions有点这个意思，但还比较早期。

另一个是Skills的自动生成。既然模型能写代码，那它能不能根据一段自然语言描述自动生成一个Skill？目前实验性的做法是让模型生成Skill的schema和实现，然后人工审核。这个方向如果成熟，Skill的开发成本会大幅下降。

还有一个是Skills的组合优化。当你有上百个Skill时，怎么让模型快速找到最相关的那几个？现在主要靠描述匹配，未来可能会用向量检索或者专门的Skill路由模型。这个在GKE上可以用独立的检索服务来实现，和Skill执行服务解耦。

我自己在实际项目里的体会是：Agent Skills的价值不在于技术多新，而在于它把AI应用开发从"手工作坊"推向了"工程化"。以前做一个Agent像写一篇作文，现在更像搭一套系统。这个转变对开发者来说意味着更高的门槛，但也意味着更可维护、更可扩展、更可复用的AI应用。如果你还在用一大坨提示词硬撑，真的可以试试把能力拆成Skills，哪怕先从两三个开始。拆完之后你会发现，调试变简单了，复用变自然了，连模型换版本都没那么可怕了。