企业官网建设流程全解析

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

第一次看到“skills”这个标题，很多人会以为是某个泛泛而谈的能力清单，或者一份简历上的技能罗列。但结合热搜词里反复出现的 Google Cloud、Agent Skills、GKE、Genkit 这些关键词，基本可以判断，这里说的 skills 不是人类职场技能，而是面向 AI Agent 的能力封装单元——也就是把一段可复用的逻辑、工具调用、提示词模板、外部 API 交互，打包成一个标准化模块，让 Agent 在需要的时候按需加载、按需执行。

我最早接触这个概念是在做自动化工作流的时候。当时每个任务都要从头写一遍工具调用逻辑，重复劳动特别多。后来发现，如果把“查数据库”“发邮件”“生成报表”这些动作各自封装成独立的 skill，Agent 就能像搭积木一样组合使用。这个思路和微服务架构很像：每个 skill 只做一件事，做好一件事，然后通过统一的接口协议被调度。

那 skills 到底能做什么？简单说，它解决的是Agent 能力复用和动态扩展的问题。没有 skills 的时候，Agent 的能力边界在部署时就固定了；有了 skills，你可以在运行时动态挂载新能力，不用重启整个系统。适合谁来参考？如果你在做 AI Agent 开发、自动化流程编排、或者想把自己的工具链接入大模型生态，那这套东西值得花时间研究。哪怕你只是用现成的 Agent 平台，理解 skills 的运作机制也能帮你更好地调试和优化。

2. 整体设计思路：为什么是“技能包”而不是“大单体”

2.1 核心思路拆解

传统做法是把所有功能写在一个大提示词里，或者把所有工具定义塞进一个配置文件。这种做法在功能少的时候没问题，一旦超过十个工具，提示词会变得极其臃肿，模型选择工具的准确率也会下降。我实测过，当工具数量超过十五个，模型选错工具的概率会明显上升，因为上下文里干扰信息太多了。

Skills 的思路是按需加载。Agent 启动时只加载一个轻量的技能索引，每个技能包含名称、描述、触发条件。当用户请求匹配到某个技能时，再把该技能的完整定义和实现加载进来。这样做的好处有三个：第一，上下文窗口占用小，模型注意力更集中；第二，技能可以独立开发、独立测试、独立部署；第三，不同团队可以并行开发不同技能，最后通过标准接口组装。

这个设计思路和 Google Cloud 上 Genkit 的工具体系是一脉相承的。Genkit 允许你把每个工具定义成独立的 flow，然后通过插件机制注册。Agent Skills 在这个基础上更进一步，把技能的生命周期管理也纳入进来——包括技能的发现、加载、执行、卸载。

2.2 方案选型背后的考量

为什么不用微调模型的方式来实现能力扩展？因为微调成本高、周期长，而且每次新增能力都要重新训练。Skills 方案是外挂式的，新增能力只需要写一个符合规范的模块，注册进去就能用。这对于快速迭代的场景来说，灵活性高太多了。

为什么不用简单的函数调用？函数调用确实能实现类似效果，但缺少标准化。每个项目的函数签名、参数格式、错误处理都不一样，导致技能无法跨项目复用。Skills 定义了一套标准协议，包括输入 schema、输出 schema、错误码、超时设置、重试策略。有了这套标准，一个团队写的技能，另一个团队可以直接拿来用。

还有一个关键考量是安全性。Skills 可以设置权限边界，比如某个技能只能读取特定目录、只能调用特定 API、只能访问特定数据库。这种细粒度的权限控制，在大单体架构里很难做到。

2.3 和 GKE 的关系

热搜词里出现了 GKE，这不是偶然的。Skills 的部署和调度天然适合容器化环境。每个 skill 可以打包成一个独立的容器镜像，通过 GKE 进行编排。这样做的好处是资源隔离——一个 skill 崩溃不会影响其他 skill；弹性伸缩——某个 skill 调用量大就多起几个实例；版本管理——不同版本的 skill 可以灰度发布。

我自己的做法是，把每个 skill 做成一个轻量 HTTP 服务，用 GKE 的 Deployment 管理，通过 Service 暴露内部端点。Agent 运行时通过服务发现找到对应的 skill 端点，发起调用。这套架构跑下来很稳，而且扩容很方便。

3. 核心细节解析：一个 Skill 到底包含什么

3.1 技能描述文件

每个 skill 的核心是一个描述文件，通常用 YAML 或 JSON 编写。这个文件定义了技能的元信息，包括：

• name：技能唯一标识，建议用蛇形命名，比如query_user_profile
• description：一句话说明技能做什么，这句话会进入模型的上下文，所以措辞要精准
• version：语义化版本号，方便管理兼容性
• input_schema：输入参数的 JSON Schema 定义
• output_schema：输出结果的 JSON Schema 定义
• trigger_conditions：什么情况下应该触发这个技能，可以用自然语言描述，也可以用关键词列表
• timeout：超时时间，单位秒
• retry_policy：重试策略，包括最大重试次数和退避算法

这里有个容易踩的坑：description 写得太泛，模型会频繁误触发；写得太窄，又该触发的时候不触发。我的经验是，description 里要包含动作 + 对象 + 典型场景。比如“查询用户档案信息，适用于需要获取用户姓名、邮箱、注册时间的场景”，就比“用户相关操作”要好得多。

3.2 输入输出 Schema 设计

Schema 设计直接决定了技能好不好用。我见过很多技能因为 schema 设计不合理，导致调用方要写大量适配代码。几个原则：

第一，参数尽量扁平。嵌套层级不要超过两层，否则模型在生成参数时容易出错。如果确实需要复杂结构，考虑拆成多个技能。

第二，必填参数要少。必填参数越多，模型调用失败的概率越高。能设默认值的就设默认值，能从上下文推断的就不要显式传。

第三，输出结构要稳定。不管内部实现怎么变，对外输出的字段名和类型要保持稳定。这样调用方不用跟着改。

第四，错误信息要结构化。不要只返回一个错误字符串，要返回错误码、错误描述、可能的修复建议。这样 Agent 可以根据错误类型决定是重试、换技能、还是向用户求助。

3.3 技能实现体的几种形态

技能实现体可以是一段代码、一个 API 调用、一个数据库查询、甚至另一个 Agent。常见形态有：

• 本地函数：用 Python、JavaScript 等语言写的函数，直接在主进程里执行。适合轻量级、无外部依赖的操作。
• 远程服务：部署在独立服务里的 HTTP 端点。适合需要独立扩缩容、有外部依赖的操作。
• 容器化任务：打包成容器镜像，按需启动。适合资源消耗大、执行时间长的操作。
• 组合技能：把多个原子技能编排成一个复合技能。适合业务流程复杂的场景。

选哪种形态，主要看执行时长、资源需求、依赖复杂度、复用频率。我一般先用本地函数快速验证，验证通过后再根据实际负载决定要不要拆成远程服务。

3.4 技能注册与发现机制

技能写好了，怎么让 Agent 知道？这就需要注册与发现机制。常见做法有两种：

一种是静态注册：在 Agent 启动时，从配置文件或数据库读取所有可用技能的列表，加载到内存里。这种方式简单直接，但新增技能需要重启 Agent。

另一种是动态发现：Agent 运行时通过服务注册中心查询可用技能。新增技能只要注册到中心，Agent 下次查询就能发现。这种方式更灵活，但实现复杂度更高。

我自己的项目用的是混合方案：核心技能静态注册，保证启动速度；扩展技能动态发现，保证灵活性。动态发现这块，可以用 etcd、Consul 或者云厂商提供的服务发现组件。

4. 实操过程：从零搭建一个可用的 Skill

4.1 环境准备与依赖安装

先说一下我的环境：Python 3.11，Node.js 20，Docker 24，kubectl 1.28。这些版本不是必须的，但建议不要太旧，否则某些依赖会装不上。

第一步，创建一个项目目录，结构如下：

my-skills/ skills/ query_user/ skill.yaml handler.py send_email/ skill.yaml handler.py registry/ registry.py agent/ main.py

第二步，安装核心依赖。我用的是 Genkit 的 Python SDK，因为它对技能注册和调度的支持比较完善：

pip install genkit genkit-plugin-google-cloud

如果你不用 Genkit，也可以用 FastAPI 自己搭一套，核心逻辑是一样的。

4.2 编写第一个 Skill：查询用户信息

先写skills/query_user/skill.yaml：

name: query_user description: 根据用户ID查询用户档案，返回姓名、邮箱、注册时间 version: 1.0.0 input_schema: type: object properties: user_id: type: string description: 用户唯一标识 required: - user_id output_schema: type: object properties: name: type: string email: type: string registered_at: type: string format: date-time timeout: 5 retry_policy: max_retries: 2 backoff: exponential

然后写skills/query_user/handler.py：

import json from datetime import datetime def handle(input_data): user_id = input_data["user_id"] # 这里模拟数据库查询，实际项目替换成真实查询 user = { "name": "张三", "email": "zhangsan@example.com", "registered_at": "2024-01-15T08:30:00Z" } if not user: return { "error_code": "USER_NOT_FOUND", "error_message": f"用户 {user_id} 不存在", "suggestion": "请检查用户ID是否正确" } return user

这里有个细节：错误返回也走 output_schema，但增加 error_code 字段。调用方先检查有没有 error_code，有就按错误处理，没有就按正常结果处理。

4.3 注册与加载技能

registry/registry.py负责扫描 skills 目录，加载所有技能：

import os import yaml import importlib.util class SkillRegistry: def __init__(self, skills_dir): self.skills = {} self.skills_dir = skills_dir def load_all(self): for skill_name in os.listdir(self.skills_dir): skill_path = os.path.join(self.skills_dir, skill_name) if not os.path.isdir(skill_path): continue with open(os.path.join(skill_path, "skill.yaml")) as f: meta = yaml.safe_load(f) handler_path = os.path.join(skill_path, "handler.py") spec = importlib.util.spec_from_file_location( f"{skill_name}_handler", handler_path ) module = importlib.util.module_from_spec(spec) spec.loader.exec_module(module) self.skills[meta["name"]] = { "meta": meta, "handler": module.handle } return self.skills def get_skill(self, name): return self.skills.get(name)

这段代码的关键点是动态导入。每个技能的 handler 是独立的 Python 文件，通过 importlib 在运行时加载，不需要提前 import。这样新增技能只要放对目录，重启 Agent 就能生效。

4.4 Agent 端调用技能

agent/main.py里，Agent 根据用户请求匹配技能并调用：

from registry.registry import SkillRegistry registry = SkillRegistry("./skills") registry.load_all() def process_request(user_input): # 这里简化处理，实际项目用模型做意图识别 if "查用户" in user_input: skill = registry.get_skill("query_user") result = skill["handler"]({"user_id": "u_12345"}) if "error_code" in result: return f"查询失败：{result['error_message']}" return f"用户：{result['name']}，邮箱：{result['email']}" return "暂不支持该操作"

实际项目中，意图识别和参数提取交给模型来做。模型根据技能列表和用户输入，输出要调用的技能名和参数，然后 Agent 执行调用。这个流程就是标准的 Agent 工具调用循环。

4.5 容器化部署到 GKE

如果技能比较多，建议容器化部署。每个技能一个 Dockerfile：

FROM python:3.11-slim WORKDIR /app COPY requirements.txt . RUN pip install -r requirements.txt COPY . . CMD ["python", "server.py"]

server.py用 FastAPI 暴露 HTTP 端点：

from fastapi import FastAPI from handler import handle app = FastAPI() @app.post("/invoke") def invoke(payload: dict): return handle(payload)

然后构建镜像、推送到镜像仓库、用 kubectl 部署到 GKE：

docker build -t my-registry/query-user:1.0.0 . docker push my-registry/query-user:1.0.0 kubectl apply -f k8s/query-user-deployment.yaml

K8s 的 Deployment 配置里，副本数先设 2，资源限制设 CPU 500m、内存 256Mi。等跑一段时间看监控数据再调整。

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

5.1 技能触发不准确怎么办

这是最常见的问题。模型该调用技能的时候不调用，不该调用的时候乱调用。排查思路：

先看 description 是不是太模糊。把 description 打印出来，让不熟悉项目的人读一遍，看能不能准确说出这个技能是干什么的。如果人说都说不清，模型更分不清。

再看技能数量是不是太多。如果同时注册了几十个技能，模型的选择难度会指数级上升。解决办法是分层注册：先注册一级分类技能，模型选中分类后再加载该分类下的具体技能。

还可以在提示词里加 few-shot 示例，给模型展示几个“用户输入 → 技能选择”的样例。实测下来，加三到五个高质量示例，准确率能提升不少。

5.2 技能执行超时怎么处理

超时问题一般出在外部依赖上。比如查数据库慢、调第三方 API 慢。处理策略：

第一，设置合理的超时时间。不要设太长，否则 Agent 会卡住；也不要设太短，否则正常请求也会超时。我的经验值是，数据库查询设 3 秒，外部 API 设 10 秒，复杂计算设 30 秒。

第二，实现重试机制。超时后自动重试，但要用指数退避，避免雪崩。第一次等 1 秒，第二次等 2 秒，第三次等 4 秒。

第三，提供降级方案。如果重试也失败，返回一个兜底结果，而不是直接报错。比如查询用户信息失败，可以返回“暂时无法获取用户信息，请稍后重试”。

5.3 技能版本冲突怎么管理

多个技能依赖同一个底层库的不同版本，这是依赖管理的经典问题。我的做法是每个技能独立虚拟环境。容器化部署天然支持这一点，每个技能镜像里装自己需要的版本，互不干扰。

如果是本地函数形态，可以用 Python 的 venv 或者 conda 环境隔离。但这样管理起来比较麻烦，技能多了之后环境切换很痛苦。所以我还是推荐容器化，虽然前期麻烦一点，但后期省心。

5.4 常见问题速查表

5.5 几个踩过的坑

第一个坑：技能名用驼峰命名。模型在生成技能名时，有时候会写成蛇形，有时候会写成驼峰，导致匹配不上。后来统一用蛇形命名，问题就少了。

第二个坑：错误信息暴露内部细节。早期版本直接把异常堆栈返回给模型，结果模型看到堆栈里的文件路径和变量名，开始胡乱猜测。后来改成只返回错误码和用户友好的描述，模型的表现稳定多了。

第三个坑：技能没有幂等性。有些技能执行两次会产生副作用，比如重复发邮件、重复扣款。后来给所有有副作用的技能加了幂等键，调用方传一个唯一 ID，技能内部根据 ID 去重。

第四个坑：忽略冷启动时间。容器化技能第一次调用要拉镜像、启动进程，耗时可能好几秒。后来给常用技能设了最小副本数，保持热实例，冷启动问题就缓解了。

6. 技能生态的扩展思路

6.1 技能市场与共享机制

当技能积累到一定数量，自然会想到共享。我们团队内部搞了一个技能市场，每个技能有独立的仓库、文档、测试用例。其他团队要用，直接引用仓库地址，在自己的 Agent 里注册就行。

共享机制的关键是接口稳定性。技能一旦发布，输入输出 schema 就不能随便改。要改就发大版本，旧版本继续维护一段时间，给调用方迁移的时间。

6.2 技能组合与编排

单个技能能力有限，组合起来才能完成复杂任务。比如“生成月度报表”这个任务，可以拆成：查询数据 → 计算指标 → 生成图表 → 发送邮件。每个步骤是一个技能，通过编排引擎串起来。

编排可以用代码写死，也可以用声明式配置。我倾向于声明式，因为改起来方便，不用重新部署。配置大概长这样：

workflow: monthly_report steps: - skill: query_data input: month: "{{month}}" - skill: calculate_metrics input: data: "{{steps.query_data.output}}" - skill: generate_chart input: metrics: "{{steps.calculate_metrics.output}}" - skill: send_email input: chart: "{{steps.generate_chart.output}}" recipient: "{{recipient}}"

这种编排方式很直观，非技术人员也能看懂。

6.3 技能性能监控

技能多了之后，性能监控很重要。我一般监控这几个指标：调用次数、平均耗时、P99 耗时、错误率、超时率。这些指标用 Prometheus 采集，Grafana 展示。

如果某个技能 P99 耗时突然飙升，可能是外部依赖出问题了，也可能是调用量突增导致资源不够。根据监控数据决定是扩容、优化代码、还是加缓存。

6.4 技能安全审计

技能能访问外部资源，所以安全审计不能少。每个技能要明确声明它需要什么权限：读哪些表、调哪些 API、访问哪些文件。部署的时候，只授予声明的权限，多一点都不给。

审计日志也要记全：谁在什么时候调用了哪个技能，传了什么参数，返回了什么结果。出了问题能追溯。

7. 我个人的一些经验体会

做技能化改造这段时间，最大的感受是粒度控制比技术实现更难。技能拆得太细，调用链太长，性能和调试都成问题；拆得太粗，复用性差，又回到了大单体的老路。我的经验是，一个技能最好对应一个完整的业务动作，而不是一个技术步骤。比如“查询用户信息”是一个完整的业务动作，“连接数据库”就是一个技术步骤，后者不应该单独做成技能。

另一个体会是文档和测试要跟上。技能是给别人用的，没有文档别人不知道怎么用，没有测试别人不敢用。我们要求每个技能必须有 README、有单元测试、有集成测试，缺一不可。前期觉得麻烦，后期省了大量沟通成本。

还有一点，不要追求一步到位。我一开始想设计一套完美的技能协议，结果拖了很久没落地。后来改成先跑通最小闭环，用最简陋的方式实现，然后根据实际使用中的痛点逐步迭代。现在这套协议已经改了五六个版本，比最初设计的完善多了，但如果没有最初那个简陋版本，根本走不到今天。

最后分享一个小技巧：给每个技能加一个dry_run模式。调用时传dry_run: true，技能只做参数校验和权限检查，不实际执行。这个模式在调试和测试的时候特别有用，能快速定位是参数问题还是执行问题。