企业官网建设流程全解析

1. 从“skills”这个热词说起：它到底在解决什么问题

最近半年，不管是在技术社区、开发者群聊，还是各种工具链的讨论里，“skills”这个词出现的频率高得离谱。Google Cloud 在推 Agent Skills，Genkit 生态里也在讲 skills，GKE 上跑智能体的时候同样绕不开这个概念。很多人第一次看到“skills”会以为是某种新框架或者新语言，其实不是。它更像是一种能力封装与复用机制——把一段可复用的逻辑、工具调用、提示词模板、甚至是一整套工作流，打包成一个独立的、可被智能体动态加载的单元。

你可以把它理解成给智能体装的“插件系统”。以前我们写一个自动化流程，往往是把所有逻辑塞进一个大函数或者一个大配置文件里，改一处就要动全身。skills 的思路是把每个独立能力拆出来，比如“查天气”“读文件”“调某个 API”“做一次分镜拆解”“写一段论文摘要”，每个能力就是一个 skill。智能体在运行过程中，根据当前任务需要，动态决定加载哪个 skill、调用哪个 skill。这样做的好处非常直接：可组合、可替换、可测试、可分发。

我最初接触这个概念是在一个 Agent Skills 的测试项目里。当时的需求是让一个智能体既能处理代码仓库里的 issue，又能顺手查一下 Google Cloud 上的日志，还要能生成一份结构化的周报。如果按传统写法，这个智能体的提示词会膨胀到几千行，维护成本极高。改成 skills 之后，每个能力独立成文件，主流程只负责编排，代码量直接降了六成，而且每个 skill 都能单独跑单元测试。从那以后我就意识到，skills 不是噱头，它是智能体工程化走到一定阶段后必然出现的基础设施。

这篇文章适合谁看？如果你是刚接触智能体开发的新手，想搞清楚 skills 到底是什么、怎么装、怎么用，那前面几节会帮你把概念理顺。如果你已经写过一些 Agent 项目，但觉得代码越来越乱、复用越来越难，那中间关于设计思路和实操细节的部分会对你有直接帮助。如果你只是好奇“codex skills”“claude agent skills”这些词为什么突然火起来，那看完你应该能判断自己要不要跟进。

提示：skills 的核心价值不在于“多了一个新名词”，而在于它把智能体的能力边界从“写死在提示词里”变成了“可动态装配的模块”。理解这一点，后面所有操作都会顺很多。

2. skills 的整体设计思路与方案选型

2.1 为什么不是“一个大提示词”而是“多个 skill”

很多人一开始会问：我直接把所有要求写进系统提示词不就行了吗，为什么要拆成 skills？这个问题我在早期也纠结过。实测下来，一个大提示词在任务简单、能力单一的时候确实够用，但只要出现下面任意一种情况，维护成本就会指数级上升。

第一种情况是能力数量超过五个。每增加一个能力，提示词里就要多一段描述、多一组示例、多几条约束。这些内容之间会互相干扰，模型很容易在某个边界条件下把两个能力的逻辑混在一起。第二种情况是不同能力需要不同的工具权限。比如读文件的 skill 需要文件系统访问，调云服务的 skill 需要网络凭证，如果全塞在一起，权限边界就模糊了。第三种情况是团队协作。一个人维护一个大提示词，别人想加功能只能在你基础上改，冲突几乎不可避免。

skills 的设计思路正好对应这三个痛点。每个 skill 是一个独立单元，有自己的描述、自己的输入输出定义、自己的依赖声明。主流程只负责“什么时候调用哪个 skill”，不关心 skill 内部怎么实现。这样一来，能力数量增加只是多几个文件，权限可以按 skill 粒度控制，团队里每个人负责自己的 skill，互不干扰。

2.2 skill 的粒度怎么定：太粗和太细都是坑

设计 skills 时最容易踩的坑就是粒度。我见过有人把一个完整的“代码审查”做成一个 skill，里面包含读 diff、查规范、写评论、发通知四个步骤。结果这个 skill 复用性极差，因为换个场景只需要“读 diff”这一步，却不得不把整个大 skill 拖进来。也见过有人把“读文件第一行”和“读文件第二行”拆成两个 skill，导致主流程里全是琐碎的调用，编排逻辑比业务逻辑还长。

我的经验是：一个 skill 应该对应一个“语义上完整、对外可独立描述”的能力。判断标准很简单——如果你能用一句话说清楚这个 skill 做什么，而且这句话里不需要出现“然后”“接着”“最后”这类连接词，那粒度基本合适。比如“查询指定日期的天气”是一个好 skill，“查询天气并生成出行建议”就偏粗了，因为后半段其实是另一个能力。

另一个实用技巧是看输入输出。如果一个 skill 的输入参数超过五个，或者输出结构嵌套超过三层，通常说明它承担了太多职责，可以考虑拆分。反过来，如果一个 skill 没有任何输入参数，输出也只是一个布尔值，那它可能太细了，更适合作为某个大 skill 的内部步骤。

2.3 选型对比：自建 skill 体系还是用现成平台

现在市面上讲 skills 的平台不少，Google Cloud 的 Agent Skills、Genkit 的 skill 机制、还有一些开源框架自带的工具注册体系。到底该自建还是直接用现成的，我整理了一个对比表，方便你按自己的情况判断。

我自己的做法是：先用现成平台跑通一个最小闭环，确认 skills 这个模式确实能解决当前问题，再决定要不要自建。如果只是做个内部工具，现成平台往往够用。如果是要做成产品的一部分，或者业务逻辑有大量定制，那自建更稳妥。自建时最关键的不是加载器写得多漂亮，而是 skill 的描述格式要稳定，因为后面所有工具链都依赖这个格式。

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

3.1 skill 的描述文件该写什么

一个 skill 能不能被正确调用，八成取决于描述文件写得好不好。我见过太多 skill 功能没问题，但因为描述写得太模糊，智能体在编排时根本不知道该选它。描述文件通常包含几个部分：名称、用途说明、输入参数定义、输出结构、依赖声明、示例。

名称要短且唯一，最好用动词开头，比如fetch_weather、parse_diff、generate_report。用途说明不要写“这个 skill 用于处理数据”这种废话，要写“根据城市名和日期查询当天天气，返回温度和天气状况”。输入参数要标明类型和是否必填，输出结构最好给一个真实示例，因为模型对示例的敏感度远高于对 schema 的敏感度。

依赖声明经常被忽略，但它很重要。如果一个 skill 需要访问网络，就要在依赖里写清楚，这样主流程在加载时能提前判断环境是否满足。示例部分我建议至少给两个：一个正常输入输出，一个边界情况。边界情况能帮模型理解这个 skill 什么时候不该被调用。

注意：描述文件里的示例不要用占位符，比如{"city": "xxx"}。要用真实值，比如{"city": "杭州", "date": "2025-03-15"}。模型对真实值的理解准确度明显更高。

3.2 加载机制：静态注册还是动态发现

skills 的加载方式主要有两种。静态注册是在启动时把所有 skill 一次性加载进内存，主流程直接按名称调用。动态发现是运行时扫描指定目录或注册中心，按需加载。两种方式各有适用场景。

静态注册的优点是快、稳定、调试简单。缺点是启动慢，skill 多了之后内存占用高，而且新增 skill 要重启服务。动态发现的优点是灵活，可以热插拔，适合 skill 数量多、更新频繁的场景。缺点是首次调用有加载延迟，而且如果发现机制写得不好，容易出现 skill 找不到或者版本混乱的问题。

我目前的项目用的是混合方案：核心 skill 静态注册，扩展 skill 动态发现。核心 skill 是那些每次运行都会用到的，比如日志、配置读取、基础工具调用。扩展 skill 是按业务场景变化的，比如不同客户有不同的报表格式，这些就放在动态目录里。这样既保证了基础能力的稳定性，又保留了业务扩展的灵活性。

3.3 参数传递与上下文隔离

skills 之间怎么传参，是实操里最容易出问题的地方。如果所有 skill 共享一个全局上下文，那写起来方便，但调试时非常痛苦，因为任何一个 skill 改了上下文，其他 skill 都可能受影响。如果每个 skill 完全隔离，那编排逻辑就要负责把所有需要的数据显式传进去，代码会啰嗦一些，但可预测性强很多。

我的建议是：默认隔离，需要共享的数据显式声明。具体做法是给每个 skill 定义清晰的输入输出，主流程负责在 skill 之间搬运数据。如果某些数据确实需要跨多个 skill 共享，比如用户身份、会话 ID，那就单独放在一个只读的上下文对象里，任何 skill 都不能修改它。这样既避免了全局污染，又不用把公共数据传来传去。

参数类型也要注意。尽量用基础类型和简单结构，避免传复杂对象。如果确实需要传复杂结构，先在主流程里序列化成字符串，skill 内部再反序列化。这样做的好处是 skill 的输入输出在日志里一目了然，排查问题时不用去猜对象里到底有什么。

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

4.1 环境准备与目录结构

假设你现在要从零搭一个 skills 体系，第一步不是写代码，而是定目录结构。我试过几种组织方式，最后稳定下来的结构是这样的：

project/ skills/ core/ fetch_weather/ skill.yaml handler.py test.py parse_diff/ skill.yaml handler.py test.py extensions/ report_weekly/ skill.yaml handler.py test.py orchestrator/ main.py loader.py config/ settings.yaml

每个 skill 一个目录，目录名就是 skill 名称。skill.yaml放描述信息，handler.py放实现逻辑，test.py放单元测试。core和extensions分开是为了区分加载策略。orchestrator放主流程和加载器。这个结构的好处是新增 skill 只需要复制一个目录，改改名字和内容就行，不需要动其他任何地方。

环境依赖方面，Python 项目建议用虚拟环境，把每个 skill 的额外依赖写在自己的requirements.txt里。加载器在加载 skill 时检查依赖是否满足，不满足就跳过并记录警告，而不是直接崩溃。这样某个 skill 缺依赖不会影响整个系统启动。

4.2 编写第一个 skill：从描述到实现

我们拿“查询天气”这个 skill 做例子。先写skill.yaml：

name: fetch_weather description: 根据城市名和日期查询当天天气，返回温度和天气状况 inputs: - name: city type: string required: true description: 城市名称，如“杭州” - name: date type: string required: true description: 日期，格式 YYYY-MM-DD outputs: - name: temperature type: number description: 摄氏度温度 - name: condition type: string description: 天气状况，如“晴”“多云” dependencies: - network examples: - input: city: "杭州" date: "2025-03-15" output: temperature: 18 condition: "多云" - input: city: "不存在的城市" date: "2025-03-15" output: error: "城市未找到"

然后写handler.py：

def run(inputs): city = inputs.get("city") date = inputs.get("date") if not city or not date: return {"error": "缺少必要参数"} # 这里调用实际的数据源，示例中省略具体实现 result = query_weather_from_source(city, date) if result is None: return {"error": "城市未找到"} return { "temperature": result["temp"], "condition": result["condition"] }

最后写test.py，至少覆盖正常情况和边界情况：

def test_normal(): result = run({"city": "杭州", "date": "2025-03-15"}) assert "temperature" in result assert "condition" in result def test_missing_param(): result = run({"city": "杭州"}) assert "error" in result def test_invalid_city(): result = run({"city": "不存在的城市", "date": "2025-03-15"}) assert "error" in result

这三个文件写完，一个 skill 就成型了。你可以单独跑测试，确认逻辑没问题，再把它注册到加载器里。

4.3 加载器实现：扫描、校验、注册

加载器的核心逻辑不复杂，但细节决定稳定性。我用的流程是：扫描目录、读取skill.yaml、校验必填字段、检查依赖、注册到内存字典。下面是一个简化版实现：

import os import yaml class SkillLoader: def __init__(self, skill_dirs): self.skill_dirs = skill_dirs self.skills = {} def load_all(self): for base_dir in self.skill_dirs: for name in os.listdir(base_dir): skill_path = os.path.join(base_dir, name) if not os.path.isdir(skill_path): continue self._load_one(skill_path) def _load_one(self, skill_path): yaml_path = os.path.join(skill_path, "skill.yaml") if not os.path.exists(yaml_path): return with open(yaml_path, "r", encoding="utf-8") as f: meta = yaml.safe_load(f) if not self._validate(meta): return if not self._check_dependencies(meta): return handler_path = os.path.join(skill_path, "handler.py") if not os.path.exists(handler_path): return self.skills[meta["name"]] = { "meta": meta, "path": skill_path } def _validate(self, meta): required = ["name", "description", "inputs", "outputs"] for key in required: if key not in meta: return False return True def _check_dependencies(self, meta): deps = meta.get("dependencies", []) for dep in deps: if dep == "network" and not self._has_network(): return False return True def _has_network(self): # 实际项目中这里做真实检查 return True

这个加载器只做了最基础的校验，实际项目中还要加版本检查、重复名称检测、循环依赖检测。但核心思路就是这样：先校验再注册，任何一步失败都跳过并记录，不阻塞其他 skill。

4.4 编排逻辑：让智能体自己选 skill

skill 注册好之后，主流程要做的事情就是根据用户输入决定调用哪些 skill。最简单的做法是写死调用顺序，但这样就失去了 skills 的意义。更好的做法是让智能体根据 skill 描述自己选择。

具体实现上，我会把当前可用的 skill 列表和它们的描述一起放进提示词，让模型输出一个调用计划。比如用户说“帮我查一下杭州明天的天气，然后写一段出行建议”，模型应该输出类似这样的计划：

[ {"skill": "fetch_weather", "inputs": {"city": "杭州", "date": "2025-03-16"}}, {"skill": "generate_advice", "inputs": {"weather": "$1.output"}} ]

其中$1.output表示引用第一个 skill 的输出。主流程按顺序执行这个计划，把每个 skill 的输出传给下一个。这样做的好处是编排逻辑和业务逻辑彻底分离，新增 skill 不需要改主流程，只需要更新可用 skill 列表。

提示：让模型输出调用计划时，一定要给它一个明确的 JSON schema，并且要求它只输出 JSON，不要加任何解释文字。否则解析起来会很痛苦。

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

5.1 skill 加载失败但没有任何报错

这是最常见的问题。现象是启动时看起来一切正常，但调用某个 skill 时提示“skill 不存在”。原因通常是加载器在_load_one里遇到了异常，但被静默吞掉了。我的做法是在每个可能失败的地方都加日志，并且把日志级别调到 WARNING 以上。另外，加载完成后打印一份已注册 skill 的清单，这样一眼就能看出哪个没加载上。

还有一种情况是skill.yaml的格式没问题，但handler.py里有语法错误。加载器只检查文件存在，不检查语法，所以注册成功了，但调用时导入失败。解决办法是在注册阶段就尝试导入 handler，导入失败就跳过并记录错误。

5.2 模型选错了 skill

模型选错 skill 通常是因为描述写得太像。比如有两个 skill，一个叫fetch_weather，一个叫get_weather，描述都是“查询天气”。模型在两者之间随机选，结果自然不稳定。解决办法是让描述有明确的区分度，比如一个写“查询实时天气”，一个写“查询历史天气”，并且在示例里体现差异。

另一个原因是 skill 数量太多，模型在长列表里注意力分散。这时候可以给 skill 加标签，主流程先根据用户输入筛选出相关标签的 skill，再把筛选后的列表给模型。这样既减少了干扰，又提高了选择准确率。

5.3 参数传递丢失或类型错误

参数传递问题多半出在编排层。比如模型输出的计划里，某个参数是数字，但 skill 期望字符串，直接传进去就会报错。我的做法是在编排层加一层参数校验和转换，按skill.yaml里定义的类型做强制转换。转换失败就返回明确的错误信息，而不是让 skill 内部去处理。

还有一种情况是引用上一个 skill 的输出时，路径写错了。比如$1.output.temperature写成了$1.temperature。这种问题在调试时很难发现，因为模型不会报错，只是传了个空值。解决办法是在编排层打印每一步的输入输出，方便对照。

5.4 常见问题速查表

5.5 几个我踩过的坑

第一个坑是 skill 名称用了中文。当时觉得中文描述更直观，结果在某些环境下编码出问题，加载器读到的名称是乱码。后来统一改成英文小写加下划线，再也没出过问题。

第二个坑是 skill 之间互相调用。一开始觉得这样能复用逻辑，后来发现调用链一长，排查问题极其困难，而且容易出现循环调用。现在的做法是 skill 之间不互相调用，所有组合逻辑都放在编排层。

第三个坑是忽略了 skill 的版本管理。同一个 skill 改了实现但没改版本号，导致不同环境跑出来的结果不一致。现在每个skill.yaml里都加version字段，加载器记录版本，编排时按版本调用。

6. skills 的扩展玩法与个人经验

6.1 把 skill 当成可测试的单元

skills 最大的隐性价值是让智能体的能力变得可测试。以前测一个智能体，只能端到端跑，输入一句话看输出对不对，中间发生了什么完全黑盒。有了 skills 之后，每个 skill 都能单独写单元测试，输入输出明确，边界情况可枚举。我现在的习惯是每写一个 skill，先写测试再写实现，这样能逼着自己把输入输出定义清楚。

测试覆盖上，我至少会写三类用例：正常输入、缺少必填参数、参数类型错误。如果 skill 涉及外部依赖，再加一类依赖不可用的用例。这些测试跑起来很快，几秒钟就能确认一个 skill 没被改坏。

6.2 用 skill 组合出复杂工作流

单个 skill 能力有限，但组合起来能做的事情很多。比如“代码审查”这个场景，可以拆成parse_diff、check_style、detect_issue、write_comment四个 skill。主流程按顺序调用，每个 skill 只做一件事。这样做的好处是每个环节都能单独优化，比如check_style的规则变了，只改这一个 skill，不影响其他环节。

组合时要注意数据格式的统一。我一般会在编排层定义一个中间数据格式，所有 skill 的输入输出都往这个格式上靠。这样 skill 之间可以自由替换，只要格式对得上就行。

6.3 关于 skill 分发的思考

skills 做多了之后，自然会想到分发和复用。团队内部可以建一个 skill 仓库，每个人把自己写的 skill 提交上去，别人按需引用。跨团队分发时，描述文件的规范性就特别重要，因为别人不了解你的业务背景，只能靠描述来判断这个 skill 能不能用。

我目前的做法是给每个 skill 打标签，比如category:network、category:text、category:code。引用方可以按标签筛选，也可以按名称精确查找。版本号用语义化版本，不兼容的改动升主版本号，兼容的新增升次版本号，修复升修订号。这样引用方可以放心升级。

6.4 我个人的几条经验

第一，不要一开始就追求大而全的 skill 体系。先写三五个最常用的 skill，跑通整个流程，再逐步扩展。我见过有人一上来就设计了二十个 skill，结果一半用不上，另一半因为需求变化频繁重写。

第二，skill 的描述文件比实现代码更重要。实现代码可以重构，但描述文件一旦被引用方依赖，改起来成本很高。所以写描述时要多想一步，考虑未来可能的扩展。

第三，日志要打够。skills 体系里调用链比单体应用长，出问题时如果没有足够的日志，排查起来非常痛苦。我现在的习惯是每个 skill 的入口和出口都打日志，记录输入输出和耗时，编排层记录调用计划。这样出问题时，看一眼日志就能定位到是哪个环节。

第四，定期清理不再使用的 skill。skills 多了之后，有些 skill 可能因为业务变化已经没人调用了，但还留在仓库里，增加维护负担。我每个季度会跑一次调用统计，把连续三个月零调用的 skill 归档。

最后再分享一个小技巧：如果你在调试某个 skill 时反复失败，先别急着改代码，把它的输入输出单独拿出来，脱离编排层跑一遍。很多时候问题不在 skill 本身，而在编排层传进来的数据不对。把 skill 单独跑通，再放回编排层，能省下大量排查时间。