企业官网建设流程全解析

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

第一次看到“agent-skills”这个标题，我脑子里蹦出来的第一个念头是：这大概率不是一个单纯的工具库，而是一套围绕“智能体能力”做拆解、封装、复用和评测的工程化方案。为什么这么判断？因为“agent”这个词在最近两年的技术圈里已经被用烂了，从对话机器人到自动化工作流，从代码助手到多模态任务执行器，几乎什么都能往里装。但“skills”这个词加在后面，性质就变了——它强调的是可插拔、可组合、可独立测试的能力单元，而不是一个包罗万象的大黑盒。

我做过几个类似形态的项目，踩过的坑基本都集中在同一个地方：一开始大家都想把智能体做成“万能助手”，结果越做越臃肿，提示词越堆越长，工具调用越来越乱，最后连开发者自己都说不清某个行为到底是哪段逻辑触发的。而“agent-skills”这个思路，本质上是把智能体从“一个会思考的大脑”拆成“一个调度器 + 一堆技能模块”。调度器负责理解意图、规划步骤、管理上下文；技能模块负责干具体的事，比如查数据、算指标、调接口、生成结构化结果。两者之间通过清晰的契约通信，谁也不用关心对方内部怎么实现。

这套思路能解决的问题非常具体。第一，复用性。你写了一个“从非结构化文本里抽取时间、地点、人物”的技能，下一个项目只要协议一致，直接挂上去就能用，不用重写提示词。第二，可测试性。技能是独立单元，输入输出明确，可以单独跑单元测试，不用每次都把整个智能体拉起来做端到端验证。第三，可观测性。哪个技能被调用了、耗时多少、返回了什么、有没有报错，全都能打点记录，排查问题的时候不用靠猜。第四，权限与安全边界。不同技能可以有不同的资源访问级别，读文件的技能和写数据库的技能天然应该隔离，拆开之后这件事变得自然。

适合谁来参考？如果你正在做智能体相关的应用开发，不管是用现成框架还是自研调度逻辑，只要遇到了“越做越乱、越改越怕”的阶段，这套拆解思路就值得认真看一遍。如果你只是刚接触智能体概念，想找一个能落地的工程化切入点，那从“技能”这个粒度入手，比一上来就啃整个调度器要友好得多。下面我会按照实际项目推进的顺序，把设计思路、核心细节、实操过程和踩坑记录一层层展开。

2. 整体设计与思路拆解：为什么是“技能”而不是“工具”或“插件”

2.1 技能、工具、插件这三个词到底差在哪

很多人会把技能、工具、插件混着用，但在工程实现上它们的边界其实挺清晰的。我自己的理解是这样的：工具偏向底层原子操作，比如“发送HTTP请求”“读取文件”“执行SQL”，它不关心业务语义，只负责把一件事做完。插件偏向平台生态里的扩展点，通常有固定的注册规范和生命周期，比如某个编辑器里的格式化插件。而技能是介于两者之间的东西——它比工具更懂业务，比插件更轻量，核心特征是“面向一个明确的意图，封装一段可复用的处理逻辑，并且能对外声明自己需要什么、能产出什么”。

举个例子你就明白了。假设你要做一个“根据用户描述生成周报”的智能体。“读取文件”是工具，“调用大模型生成文本”也是工具。但“从聊天记录里提取本周完成事项”就是一个技能，它内部可能会调用读取文件工具、文本清洗工具、大模型抽取工具，最后输出一个结构化的任务列表。再往上，“生成周报”本身也可以是一个技能，它依赖“提取完成事项”这个技能，再加上“格式化输出”技能。这样一层层组合起来，整个系统的复杂度就被拆散了。

为什么不用“工具”这个粒度？因为工具太底层，直接暴露给调度器会导致提示词里塞满各种参数说明，调度器很难做高层规划。为什么不用“插件”？因为插件通常和特定平台绑定，换一个运行环境就要重写注册逻辑，不够纯粹。技能这个粒度刚好卡在“业务语义清晰”和“实现方式自由”之间，是我试过之后觉得最舒服的切分点。

2.2 调度器与技能的契约设计：输入输出协议怎么定

拆开之后，第一件要定的事就是契约。调度器怎么知道有哪些技能可用？怎么知道每个技能需要什么参数？怎么知道调用完会返回什么？这些问题的答案必须在一个统一的协议里说清楚，否则技能一多就会乱。

我一般会定义一个技能描述结构，至少包含这几个字段：技能名称、功能简述、输入参数列表（每个参数有名称、类型、是否必填、描述）、输出结构描述、以及可选的示例。这个结构可以用JSON Schema来表达，也可以用更轻量的自定义格式，关键是调度器能解析、大模型能理解。

这里有个经验：描述字段的措辞比结构本身更重要。我见过很多项目把技能描述写得像API文档，全是“参数A：字符串，必填”，结果大模型根本不知道怎么用。正确的做法是用自然语言把“什么时候该用这个技能”说清楚。比如不要写“extract_time：提取时间”，而要写“当用户提到具体日期、时间段或相对时间表达时，用这个技能把文本里的时间信息抽成标准格式”。前者是给机器看的，后者是给模型看的，两者都要有，但后者往往决定了调用准确率。

输出结构也要提前约定。我踩过一个坑：早期技能返回的是自由文本，调度器拿到之后还要再解析一遍，结果格式稍微一变就崩。后来改成强制返回结构化数据，比如统一用带字段的JSON，调度器直接按字段取值，稳定性立刻上了一个台阶。如果某个技能确实需要返回大段文本，那就把它放在一个固定字段里，外层结构不变。

2.3 为什么不做成一个“全能智能体”

这个问题我被问过很多次。做一个大而全的智能体，把所有逻辑写在一个提示词里，看起来不是更简单吗？短期看确实简单，长期看是灾难。我总结下来有三个致命问题。

第一，提示词膨胀导致注意力稀释。当你的提示词从五百字涨到五千字，模型对每一条指令的遵循程度是下降的。你写了几十条规则，它可能只记住前十条和后十条，中间的全忽略了。拆成技能之后，每个技能的提示词都很短，模型在调用某个技能时只需要关注这个技能相关的几条规则，准确率自然高。

第二，错误定位困难。全能智能体出错的时候，你很难判断是理解错了、规划错了、还是执行错了。拆成技能之后，每个环节的输入输出都有记录，一看就知道是哪一步偏了。这个可观测性在调试阶段价值巨大。

第三，无法独立迭代。全能智能体里改一个行为，可能影响其他九个行为。技能化之后，你改“提取时间”这个技能，只要输入输出协议不变，其他技能完全不受影响。这种局部可修改性，是系统能长期维护的前提。

2.4 技能粒度的划分原则

粒度太粗，等于没拆；粒度太细，调度开销爆炸。我一般用两个标准来判断：一个技能是否对应一个清晰的意图，以及一个技能是否可以被独立测试。如果一段逻辑你没法用一句话说清它“在什么情况下被调用、做完之后产出什么”，那它就不适合做技能。如果一段逻辑你没法单独给它写测试用例，那它要么太依赖上下文，要么职责不单一。

举个反例。有人把“调用大模型”本身封装成一个技能，这就不太合适，因为几乎所有技能内部都要调大模型，它更像是一个基础设施，而不是一个业务技能。再比如“格式化输出”这种技能，如果只是简单拼字符串，那没必要单独拆；但如果它涉及多种模板选择、字段映射、校验规则，那拆出来就有价值。粒度这件事没有标准答案，我的经验是先粗后细，等发现某个技能内部逻辑太杂或者被复用的频率特别高时，再往下拆一层。

3. 核心细节解析与实操要点：技能模块内部到底怎么写

3.1 技能的生命周期：注册、发现、调用、回收

一个技能从被系统知道到被真正执行，中间要经过几个阶段，每个阶段都有细节要注意。

注册阶段，技能需要把自己的描述信息告诉调度器。常见做法有两种：一种是启动时扫描指定目录，自动加载所有技能定义；另一种是显式注册，在配置文件里列出启用的技能。前者适合技能数量多、变动频繁的场景，后者适合需要严格控制可用技能集的场景。我一般用混合方式：目录扫描负责发现，配置文件负责开关和优先级。

发现阶段，调度器在规划任务时，需要从所有已注册技能里筛选出当前可能用到的几个。如果技能数量少，可以全部塞进提示词；如果数量多，就需要先做一轮检索。检索可以基于关键词匹配，也可以基于向量相似度。我实测下来，技能描述写得好的话，关键词匹配的准确率已经够用，向量检索更适合描述风格差异大的场景。

调用阶段，调度器决定用某个技能后，要把参数准备好传进去。这里有个关键点：参数校验必须在调用前做。我见过太多因为参数缺失或类型不对导致技能内部报错的情况，如果能在调用前拦截并返回明确的错误信息，调度器就有机会重新规划或者向用户追问。校验逻辑可以基于前面定义的输入参数结构自动生成，不用手写。

回收阶段，技能执行完要释放资源。如果技能内部开了数据库连接、临时文件、子进程，一定要在finally块里清理。我踩过一个坑：某个技能每次调用都创建一个临时目录，但异常路径下没删，跑了几百次之后磁盘满了。后来统一加了一个资源管理包装层，所有技能执行完自动清理注册过的资源，这类问题就再没出现过。

3.2 提示词在技能内部的角色与写法

技能内部如果要用到大模型，提示词的设计就非常关键。我的原则是：技能内部的提示词只关注当前技能这一件事，不要掺杂全局规则。全局规则比如“回答要礼貌”“不要泄露隐私”应该放在调度器层或者系统层统一处理，技能层只负责把输入转成输出。

具体写法上，我习惯把提示词分成三段：角色设定、任务说明、输出格式。角色设定一句话就够，比如“你是一个专门从文本中抽取结构化信息的助手”。任务说明要具体到输入字段和输出字段的对应关系，最好给一两个例子。输出格式要严格，能用JSON就用JSON，并且在提示词里明确说“只输出JSON，不要输出其他内容”。这三段加起来通常不超过三百字，模型遵循起来很稳。

还有一个技巧：把校验逻辑写进提示词。比如要求输出里的时间字段必须是ISO格式，那就在提示词里写“时间字段必须形如2024-01-15T09:30:00”。模型看到具体格式示例，比只写“标准时间格式”要准确得多。如果模型还是偶尔输出错，那就在技能代码里再加一层后处理校验，双保险。

3.3 技能之间的依赖与编排

技能不是孤立的，有些技能会依赖其他技能的输出。比如“生成周报”依赖“提取完成事项”，“提取完成事项”又依赖“读取聊天记录”。这种依赖关系怎么管理？

最简单的方式是让调度器负责编排，技能之间不直接调用。调度器先调“读取聊天记录”，拿到结果后再调“提取完成事项”，最后调“生成周报”。这样每个技能都是无状态的，只依赖输入，不依赖其他技能的存在。好处是灵活，调度器可以根据情况调整顺序或跳过某些步骤。坏处是调度器逻辑会变复杂，尤其是依赖链很长的时候。

另一种方式是允许技能内部调用其他技能，形成一个技能树。这种方式适合依赖关系稳定的场景，比如“生成周报”永远需要“提取完成事项”的结果，那就可以在技能内部直接调。但要注意避免循环依赖，A调B、B又调A，会直接死循环。我一般会在技能注册时记录依赖关系，启动时做一次拓扑排序检查，有环就报错。

实际项目中我倾向于混合：核心的、稳定的依赖放在技能内部，灵活的、可变的编排放在调度器层。判断标准是“这个依赖是不是永远成立”。如果是，内聚到技能里；如果不是，交给调度器。

3.4 错误处理与降级策略

技能执行失败是常态，不是异常。网络会抖、接口会挂、模型会抽风，这些都要提前想好怎么处理。

我的做法是把错误分成三类。可重试错误，比如网络超时、限流，这类错误自动重试两到三次，每次间隔递增。可降级错误，比如某个数据源不可用，但有备用数据源，那就切换到备用源，同时在结果里标记降级信息。不可恢复错误，比如参数根本不对、依赖的服务彻底下线，这类错误直接向上抛，让调度器决定是追问用户还是终止任务。

降级策略特别值得展开说。我做过一个技能是“查询某指标的最新值”，主数据源是一个实时接口，备用数据源是一个每天更新一次的离线表。正常情况下走实时接口，接口超时或报错时自动切到离线表，并在返回结果里加一个字段说明数据时效性。这样上层拿到结果时知道数据可能不是最新的，可以决定要不要提示用户。如果没有这个降级设计，接口一挂整个任务就失败了，用户体验很差。

还有一个细节：错误信息要包含足够的上下文。不要只抛一个“调用失败”，要带上技能名称、输入参数摘要、错误类型、原始错误信息。这样排查的时候不用再去翻日志。但要注意别把敏感数据写进错误信息，比如用户ID、密钥之类的，该脱敏的要脱敏。

4. 实操过程与核心环节实现：从零搭一个技能化智能体

4.1 环境准备与目录结构

假设我们要做一个“会议纪要助手”，核心功能是：读取会议录音转写文本，提取待办事项，按负责人分组，生成结构化纪要。按照技能化思路，我会拆成三个技能：文本清洗技能、待办提取技能、分组汇总技能。下面按这个例子走一遍完整流程。

目录结构我一般这样组织：

project/ skills/ text_cleaner/ skill.json handler.py prompt.txt todo_extractor/ skill.json handler.py prompt.txt todo_grouper/ skill.json handler.py scheduler/ planner.py executor.py config/ skills.yaml tests/ test_text_cleaner.py test_todo_extractor.py

每个技能一个目录，里面放技能描述文件、处理逻辑、提示词模板。调度器单独一个目录，配置单独一个目录，测试单独一个目录。这个结构的好处是技能可以整体复制到其他项目，只要把目录拷过去、在配置里启用就行。

4.2 技能描述文件的编写

以“待办提取”技能为例，skill.json大概长这样：

{ "name": "todo_extractor", "description": "当输入是一段会议转写文本，需要从中提取待办事项时使用此技能。输入应为清洗后的纯文本，输出为待办事项列表。", "input": { "text": { "type": "string", "required": true, "description": "清洗后的会议转写文本" } }, "output": { "todos": { "type": "array", "description": "待办事项列表，每项包含内容、负责人、截止时间三个字段" } }, "examples": [ { "input": {"text": "小王下周把方案初稿发出来，小李这周五前确认预算。"}, "output": {"todos": [{"content": "发方案初稿", "owner": "小王", "deadline": "下周"}, {"content": "确认预算", "owner": "小李", "deadline": "这周五前"}]} } ] }

注意description字段的写法，它明确说了“什么时候用”，而不是“这个技能是什么”。examples字段给了具体输入输出，模型看了之后对格式的理解会准确很多。这两个细节是我试过之后觉得对调用准确率提升最明显的。

4.3 技能处理逻辑的实现

handler.py是技能的实际执行入口。我一般会定义一个统一的函数签名，比如def execute(inputs: dict) -> dict，输入输出都是字典。内部逻辑分三步：参数校验、核心处理、结果封装。

参数校验用前面定义的input结构自动生成校验逻辑，缺字段或类型不对直接抛明确错误。核心处理如果是调大模型，就把prompt.txt读进来，把输入变量填进去，调模型，拿结果。结果封装要确保输出结构和skill.json里声明的一致，不一致就报错。

这里有个实操细节：模型返回的JSON要容错解析。模型有时候会在JSON外面包一层json，有时候会多输出一句解释。我一般会先尝试直接解析，失败就找第一个{和最后一个}之间的内容再解析，再失败就报错。这个容错逻辑我封装成了一个公共函数，所有技能共用。

4.4 调度器的规划与执行

调度器收到用户请求后，先做意图理解，判断需要哪些技能。简单场景可以用规则匹配，复杂场景用大模型做规划。规划结果是一个技能调用序列，比如[text_cleaner, todo_extractor, todo_grouper]。

执行时按顺序调用，每个技能的输出作为下一个技能的输入。如果某个技能失败，根据错误类型决定重试、降级还是终止。执行过程中记录每个技能的输入输出和耗时，方便后续排查。

调度器的提示词里要包含所有可用技能的描述，但不需要包含技能内部的实现细节。描述要精简，只保留name、description和输入输出字段名。如果技能太多塞不下，就先做一轮检索，只把相关的几个塞进去。

4.5 测试与验证

技能化最大的好处之一就是可以单独测试。每个技能我都要求至少覆盖三种情况：正常输入、边界输入、异常输入。正常输入验证核心功能，边界输入比如空文本、超长文本、特殊字符，异常输入比如缺字段、类型错误。

测试用pytest就行，每个技能一个测试文件。跑测试的时候不需要启动调度器，直接调技能的execute函数。这样测试速度快，定位问题也准。等所有技能单测通过后，再做端到端测试，验证调度器的编排逻辑。

我一般还会加一个“回归测试集”，把历史上出过问题的输入输出对存下来，每次改动后跑一遍，确保没有引入新的回归。这个习惯帮我省了很多事，尤其是改提示词的时候，很容易顾此失彼，有了回归集就能快速发现。

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

5.1 技能调用准确率低怎么办

这是最常见的问题。模型该调A技能的时候调了B，或者该调的时候没调。排查思路分三层。

先看技能描述。描述里有没有说清“什么时候用”？如果只写了功能没写触发条件，模型很难判断。改法是把触发条件写进description，比如“当用户询问具体数值时使用”比“查询数值”要好得多。

再看技能数量。如果一次塞给模型的技能超过十个，准确率会明显下降。这时候要么做检索筛选，要么做技能分组，让模型先选组再选技能。

最后看示例。examples字段如果和实际输入风格差异大，模型会困惑。示例要尽量贴近真实场景，输入输出的格式要和实际一致。

5.2 技能之间参数传递出错

多技能串联时，上游输出和下游输入对不上是高频问题。比如上游返回{"todos": [...]}，下游期望{"items": [...]}，字段名不一致直接报错。

解决办法是在调度器层加一个字段映射配置，或者统一约定字段命名规范。我倾向于后者，所有技能的输出字段名尽量用通用词汇，比如列表统一叫items，文本统一叫text，时间统一叫timestamp。这样技能之间对接的时候不用额外转换。

如果确实需要映射，就在调度器的执行配置里写清楚，比如todo_extractor.todos -> todo_grouper.items。这个映射关系集中管理，比散落在各个技能里好维护。

5.3 模型输出格式不稳定

即使提示词里写了“只输出JSON”，模型偶尔还是会加解释文字或者格式跑偏。除了前面说的容错解析，还可以在提示词里加更强的约束，比如“你的输出将被程序直接解析，任何非JSON内容都会导致解析失败”。这句话对模型有一定威慑作用，实测能降低格式错误率。

另一个技巧是用模型的JSON模式（如果API支持）。开启之后模型会保证输出合法JSON，省去很多解析麻烦。但要注意JSON模式下模型可能无法输出某些特殊字符，需要提前测试。

5.4 技能执行超时

有些技能内部调外部接口或者大模型，耗时可能很长。调度器要设置合理的超时时间，超时后要么重试要么降级。超时时间设多少？我的经验是看P95耗时，设成P95的两到三倍。比如大部分调用两秒完成，偶尔五秒，那超时设十秒比较合适。

如果某个技能经常超时，要考虑是不是内部逻辑太重。可以拆成更细的技能，或者把耗时操作异步化。异步化之后调度器需要支持等待和回调，复杂度会上升，要权衡。

5.5 常见问题速查表

5.6 几个我踩过的坑

第一个坑是技能描述写得太技术化。早期我写描述喜欢用“输入为字符串，输出为数组”这种API文档风格，结果模型调用准确率很低。后来改成自然语言描述使用场景，准确率明显提升。这个转变花了我不少时间才意识到。

第二个坑是没有做技能版本管理。改了一个技能的提示词，结果依赖它的上游技能行为变了，但没人知道。后来给每个技能加了版本号，调度器配置里锁定版本，升级时显式改配置，问题就少了。

第三个坑是过度拆分。有一段时间我追求“一个技能只做一件事”，拆得特别细，结果调度器要调十几个技能才能完成一个任务，延迟高、出错概率也高。后来回归到“一个技能对应一个业务意图”的粒度，平衡了复用性和执行效率。

第四个坑是忽略技能的资源消耗。某个技能内部加载了一个大模型到内存，每次调用都重新加载，导致内存暴涨。后来改成技能初始化时加载一次，后续复用，内存问题解决。技能如果有重资源，一定要考虑生命周期管理，不能每次调用都重建。

6. 技能化智能体的扩展方向与个人体会

这套技能化思路跑通之后，扩展空间其实挺大的。我目前尝试过的几个方向包括：技能市场，把通用技能打包成可分享的模块，新项目直接引入；技能自动生成，用大模型根据需求描述自动生成技能骨架和提示词初稿，人工再微调；技能性能分析，统计每个技能的调用频率、成功率、平均耗时，找出瓶颈和冗余。

还有一个方向是技能的组合优化。当技能数量多了之后，调度器规划出的调用序列可能不是最优的，比如有冗余步骤或者可以并行执行的步骤被串行了。我试过用简单的规则做优化，比如识别可并行的技能、合并连续的同类型操作，效果还不错。更复杂的优化可能需要引入规划算法，但那个复杂度就上去了，要看实际需求。

我个人在实际操作中的体会是，技能化最大的价值不在于技术本身，而在于它强迫你把“智能体到底在干什么”这件事想清楚。当你试图把一个行为拆成独立技能时，你会被迫回答：它的输入是什么、输出是什么、什么时候该用、失败了怎么办。这些问题在单体智能体里往往被模糊掉了，但恰恰是系统能否稳定运行的关键。拆的过程很痛苦，拆完之后维护起来是真的轻松。

最后分享一个小技巧：如果你不确定某个逻辑该不该拆成技能，就先把它写成一个函数，看看它被调用的频率和场景。如果只在一个地方用、逻辑也不复杂，那就先不拆；如果多个地方都要用、或者逻辑开始膨胀，那就拆。技能化不是目的，可维护性才是。