企业官网建设流程全解析

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

第一次看到"skills"这个标题，加上Google Cloud、GKE、Genkit这几个关键词，我脑子里第一反应是：这大概率不是指人类技能，而是指Agent Skills——也就是给AI智能体挂载的"能力包"。最近一段时间，围绕Agent Skills的讨论确实密集，从Claude的Agent Skills到Codex的skills，再到各种skills市场、skills下载平台，热度一直没降下来。

但问题在于，"skills"这个词太泛了。它可以是前端开发skills，可以是superpower skills，也可以是自动挖洞skills。不同语境下，它指向的东西完全不同。所以这篇内容我打算做一件事：把"skills"这个概念从模糊拉回到具体，讲清楚它在Agent场景下到底是什么、为什么会出现、怎么设计、怎么落地，以及围绕Google Cloud这套技术栈（GKE + Genkit）能怎么玩。

如果你是一个正在做AI Agent应用的开发者，或者你只是好奇"为什么大家都在聊skills"，这篇内容应该能帮你把思路理顺。我不会只讲概念，会带上具体的结构设计、代码示例、部署思路，以及我自己在实操中踩过的坑。

先给一个最直白的定义：Agent Skill本质上是一段可被智能体识别、加载、执行的能力描述单元。它通常包含三部分——元信息（这个skill叫什么、干什么用）、触发条件（什么情况下该调用它）、执行逻辑（具体怎么做）。你可以把它理解成给AI写的一份"岗位说明书+操作手册"。

为什么这个东西突然火了？因为大模型本身是"通才"，但通才在具体任务上往往不够专。你让一个通用模型去处理GKE集群的滚动更新，它可能给你一堆似是而非的命令。但如果你给它挂一个专门针对GKE的skill，里面写清楚了正确的kubectl命令、回滚策略、健康检查逻辑，它的输出质量会立刻上一个台阶。

这就是skills的核心价值：把领域知识从模型参数里"外挂"出来，变成可维护、可复用、可版本控制的独立单元。模型负责理解和调度，skill负责提供准确的动作。

2. Agent Skills的底层逻辑：为什么不是简单的Prompt

很多人第一次接触skills，会觉得"这不就是高级一点的Prompt吗"。我一开始也这么想，但实际用下来发现，两者有本质区别。理解这个区别，是设计好skill的前提。

2.1 Prompt是"一次性对话"，Skill是"可复用能力"

Prompt是你每次对话时临时写的一段指令，用完就散了。Skill不一样，它是一个持久化的、有结构的、可被检索的能力单元。当智能体遇到某个任务时，它会先去"找skill"——就像人遇到问题会先想"我有没有相关经验"一样。

这个"找"的过程，就是skills体系里最关键的一环。它通常依赖两层机制：

• 元数据匹配：每个skill都有name和description，智能体先通过语义相似度筛选出候选skill。
• 内容加载：选中之后，才把skill的完整内容（通常是Markdown格式的操作指南）加载进上下文。

这样做的好处是上下文经济。你不可能把所有领域知识都塞进系统提示里，那样token会爆炸。Skills让你按需加载，用哪个调哪个。

2.2 Skill的结构：元信息、触发、执行三段式

一个设计良好的skill，我一般会拆成三段：

元信息里的description尤其重要。它写得好不好，直接决定智能体能不能在正确的时机找到这个skill。我见过太多skill因为description写得太笼统（比如"处理数据库相关操作"），导致该调用的时候调不到，不该调用的时候乱调。

2.3 和Function Calling的关系

有人会问：这和Function Calling有什么区别？我的理解是，Function Calling是模型调用外部函数的机制，而Skill是给模型看的操作知识。一个skill内部可以包含多个function call，也可以只是一段纯文本的操作指南。

举个例子：一个"GKE集群健康检查"的skill，可能包含：

• 一段说明文字：告诉智能体检查哪些指标
• 几个命令：kubectl get nodes、kubectl describe pod等
• 判断逻辑：什么情况下算异常
• 处理建议：异常时该怎么回滚或扩容

这里面既有知识，也有动作。Function Calling只解决了"动作"那一半，Skill把"知识"那一半也补上了。

3. 用Genkit搭建Skill调度层：从零到跑通

Genkit是Google推出的AI应用开发框架，它的定位是帮你把模型调用、工具编排、流程控制这些事串起来。用它来做skills的调度层，我觉得挺顺手，因为它对"工具"这个概念的支持很自然。

3.1 环境准备与项目初始化

先装依赖。我习惯用Node环境，因为Genkit对TypeScript的支持最完整：

npm init -y npm install genkit @genkit-ai/googleai npm install -D typescript tsx

然后初始化Genkit配置：

import { genkit } from 'genkit'; import { googleAI } from '@genkit-ai/googleai'; export const ai = genkit({ plugins: [googleAI()], model: 'googleai/gemini-2.0-flash', });

这里有个小坑：模型选择要和你的skill复杂度匹配。如果skill里涉及多步推理和工具调用，用flash可能会在中间步骤掉链子，建议上pro。我实测下来，简单skill用flash够用，复杂的还是pro稳。

3.2 把Skill定义成Genkit Tool

Genkit里的tool概念，天然适合承载skill的执行部分。你可以这样定义一个skill：

import { z } from 'genkit'; import { ai } from './genkit-config'; export const gkeHealthCheck = ai.defineTool( { name: 'gkeHealthCheck', description: '检查GKE集群节点和Pod的健康状态，返回异常列表', inputSchema: z.object({ clusterName: z.string().describe('GKE集群名称'), namespace: z.string().optional().describe('命名空间，默认default'), }), outputSchema: z.object({ healthy: z.boolean(), issues: z.array(z.string()), }), }, async (input) => { // 这里放实际的检查逻辑 // 可以是调用kubectl，也可以是调用GKE API const issues: string[] = []; // ... 检查逻辑 return { healthy: issues.length === 0, issues }; } );

注意description的写法。我特意写清楚了"检查节点和Pod的健康状态，返回异常列表"，这样智能体在遇到"集群是不是有问题"这类问题时，能准确匹配到这个skill。

3.3 让智能体自动选择Skill

定义好tool之后，Genkit可以自动处理"什么时候调用哪个tool"。你只需要在生成时把tools传进去：

const response = await ai.generate({ prompt: '帮我看看生产集群现在有没有问题', tools: [gkeHealthCheck], });

Genkit会根据prompt和tool的description做匹配。如果匹配上了，它会自动调用并返回结果。这一步的体验很顺，但前提是你的description写得够准。

3.4 多Skill编排的注意事项

当你有一堆skill的时候，问题就来了：智能体可能选错，或者一次选太多。我的经验是：

• 每个skill的description要互斥，不要有重叠的语义。比如"检查集群健康"和"诊断集群问题"就容易混。
• 控制单次可用的skill数量。我一般不超过10个，多了就分组，按场景加载。
• 给skill加优先级或场景标签，在prompt里做前置过滤。

这些细节在官方文档里不会写，但实际项目里不注意就会翻车。

4. 部署到GKE：让Skill服务真正跑起来

Skill定义好了，Genkit流程也跑通了，接下来就是部署。GKE是Google的Kubernetes服务，用它来托管skill服务，好处是弹性伸缩和滚动更新都很成熟。

4.1 容器化Skill服务

先把Genkit应用打包成镜像。Dockerfile大概长这样：

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

Genkit默认跑在3400端口。构建镜像：

docker build -t skill-service:v1 .

4.2 GKE部署清单的关键字段

部署到GKE，核心是Deployment和Service两个资源。我重点说几个容易配错的字段：

apiVersion: apps/v1 kind: Deployment metadata: name: skill-service spec: replicas: 2 selector: matchLabels: app: skill-service template: metadata: labels: app: skill-service spec: containers: - name: skill-service image: skill-service:v1 ports: - containerPort: 3400 resources: requests: memory: "512Mi" cpu: "250m" limits: memory: "1Gi" cpu: "500m" readinessProbe: httpGet: path: /health port: 3400 initialDelaySeconds: 10 periodSeconds: 5

几个经验点：

• readinessProbe一定要配。Genkit服务启动需要加载模型配置，没配探针的话，流量会在服务没准备好时就打进来，导致请求失败。
• resources的requests和limits要拉开差距。skill服务的特点是平时CPU低、突发时高，requests给低一点保证调度，limits给高一点应对峰值。
• replicas至少2个。单副本在滚动更新时会有短暂不可用，2个能保证平滑。

4.3 滚动更新与回滚策略

GKE默认的滚动更新策略是maxSurge 25%、maxUnavailable 25%。对于skill服务，我建议调保守一点：

strategy: type: RollingUpdate rollingUpdate: maxSurge: 1 maxUnavailable: 0

maxUnavailable设为0，意味着新Pod完全就绪之前，旧Pod不会被干掉。这样更新过程中服务始终可用。代价是更新慢一点，但skill服务通常不是高频更新，慢一点无所谓。

回滚就更简单了：

kubectl rollout undo deployment/skill-service

但要注意，回滚只回滚镜像，不回滚配置。如果你的skill定义是挂在ConfigMap里的，回滚镜像后配置可能不匹配。我的做法是把skill定义和镜像版本绑定，一起发布一起回滚。

4.4 用ConfigMap管理Skill定义

Skill的文本内容（那些Markdown操作指南）不适合硬编码在代码里，放ConfigMap更灵活：

apiVersion: v1 kind: ConfigMap metadata: name: skill-definitions data: gke-health-check.md: | # GKE健康检查 检查以下内容： 1. 节点状态：kubectl get nodes 2. Pod状态：kubectl get pods --all-namespaces 3. 异常事件：kubectl get events --sort-by=.lastTimestamp

这样改skill内容不用重新构建镜像，改ConfigMap然后重启Pod就行。但记得ConfigMap更新后Pod不会自动重载，需要手动触发滚动重启：

kubectl rollout restart deployment/skill-service

5. Skill设计中的常见坑与排查思路

这部分是我最想写的，因为网上讲skill概念的多，讲实际踩坑的少。下面这几个问题，我几乎在每个项目里都遇到过。

5.1 Skill匹配不上：description写得太"聪明"

最常见的坑：智能体该调用skill的时候不调用。排查下来，十有八九是description的问题。

我见过有人把description写成"处理集群相关的高级操作"。这种描述对人是清楚的，但对语义匹配来说太模糊。"高级操作"是什么？智能体不知道。

正确的写法是用具体的动作和对象：

检查GKE集群的节点状态、Pod运行情况和最近事件，返回异常项列表

这句话里有动作（检查）、对象（节点、Pod、事件）、输出（异常列表）。智能体一看就知道什么时候该用。

5.2 Skill被滥用：触发条件太宽

反过来，也有skill被乱调用的情况。比如一个"发送通知"的skill，description写的是"发送消息"，结果智能体在任何需要输出的时候都去调它。

解决办法是在description里加约束：

当需要向指定渠道（如邮件、Slack）发送格式化通知时使用。不用于普通对话回复。

明确写出"不用于什么"，能大幅减少误调用。

5.3 多Skill冲突：语义重叠的排查方法

当你有几十个skill的时候，语义重叠几乎不可避免。我的排查方法是：

1. 把所有skill的description列出来，两两做语义相似度对比。
2. 相似度超过阈值的，要么合并，要么改写description拉开差异。
3. 在测试环境跑一批典型prompt，看智能体的选择是否符合预期。

这个工作很枯燥，但做一次能省掉后面无数次的调试。

5.4 上下文超限：Skill内容太长被截断

Skill的完整内容是要加载进上下文的。如果一个skill写了5000字，加上其他上下文，很容易超限。我的经验是：

• 单个skill的正文控制在800字以内。
• 超长的操作指南拆成多个skill，用主skill做索引。
• 把不常变的部分（如背景知识）放到外部文档，skill里只放操作步骤。

5.5 排查链路：一个真实的匹配失败案例

说个具体的。有次上线后，用户反馈"问集群扩容的事，智能体答非所问"。我的排查过程是这样的：

第一步，复现问题。用同样的prompt测试，确认确实没调用扩容skill。

第二步，检查skill是否被加载。看日志，发现skill在候选列表里，但没被选中。

第三步，对比description。扩容skill的description是"调整集群规模"，而另一个"资源优化"skill的description是"优化集群资源配置"。两者语义太近，智能体选了后者。

第四步，改写。把扩容skill改成"增加或减少GKE集群的节点数量"，把资源优化改成"调整Pod的CPU和内存请求配额"。改完之后，匹配准确率明显提升。

这个案例说明，skill设计不是一劳永逸的，需要根据实际调用数据持续迭代。

6. Skill的版本管理与团队协作

一个人用skill和团队用skill，复杂度完全不是一个量级。团队协作场景下，版本管理和规范约定特别重要。

6.1 Skill的版本控制策略

我建议把skill定义纳入Git管理，和代码一起走PR流程。目录结构可以这样：

skills/ gke/ health-check.md scale-cluster.md genkit/ deploy-flow.md _index.yaml

_index.yaml记录所有skill的元信息，方便程序加载。每次改skill都走PR，有人review，避免有人随手改坏了description导致匹配失效。

6.2 命名规范：让Skill可检索

命名这件事，我踩过坑。早期我用的是"checkCluster"这种驼峰命名，后来发现检索不方便。现在统一用领域-动作的格式：

• gke-health-check
• gke-scale-cluster
• genkit-deploy-flow

这样按领域前缀一搜就能找到一组相关skill。

6.3 测试：Skill的单元测试怎么写

Skill也需要测试。我的做法是给每个skill写一组"触发用例"：

const testCases = [ { prompt: '集群现在健康吗', expectedSkill: 'gke-health-check' }, { prompt: '帮我扩容到5个节点', expectedSkill: 'gke-scale-cluster' }, { prompt: '今天天气怎么样', expectedSkill: null }, ];

跑一遍，看智能体的选择是否和预期一致。这个测试不用很频繁，但每次改description之后一定要跑。

6.4 团队共享Skill的注意事项

团队共享skill，最大的问题是上下文差异。A同学写的skill假设了某个环境变量存在，B同学用的时候没有，就报错。解决办法是在skill里明确写出前置依赖：

前置条件：需要配置GKE_PROJECT_ID和GKE_CLUSTER_NAME环境变量。

把依赖写清楚，比事后排查省事得多。

7. 从Skills延伸出去：还能怎么玩

Skills这套思路，其实不局限于Agent。它的本质是把隐性知识显性化、结构化、可复用化。这个思路可以迁移到很多场景。

比如前端开发skills，可以把组件库的使用规范、常见布局模式、性能优化checklist做成skill，让AI辅助写代码时直接调用。再比如自动挖洞skills，可以把常见漏洞的检测逻辑和验证步骤结构化，提升安全测试的效率。

我甚至见过有人把"分镜设计"做成skill，输入剧本，输出分镜描述。这说明skills的边界只取决于你怎么定义它。

回到Google Cloud这套栈，Genkit + GKE的组合，我觉得最适合做的是企业内部的能力中台。把各个团队的专业能力做成skill，统一注册、统一调度，智能体按需调用。这样既避免了重复建设，又保证了能力的一致性。

最后分享一个我自己的体会：skill的质量，取决于你对业务的理解深度，而不是你对AI的调参技巧。一个对GKE运维了五年的工程师写出来的skill，一定比一个刚学Kubernetes的人写得好。所以做skills这件事，别只盯着模型，多花时间在领域知识上，回报会更高。