企业官网建设流程全解析

1. 从"agent-skills"这个标题说起：我理解的智能体能力体系

第一次看到"agent-skills"这个标题的时候，我脑子里蹦出来的第一个画面是游戏里的技能树——每个角色有自己的一套技能面板，点哪个、怎么加点、技能之间怎么联动，直接决定了这个角色在实战里能不能打。智能体（Agent）这个东西，本质上和游戏角色是一回事：底层模型是它的"基础属性"，而skills就是它后天习得、可以灵活调用的"技能包"。你给一个智能体配了什么样的skills，它就能干什么样的活儿，这个逻辑非常直白。

但真正让我觉得这个标题值得深挖的，是"skills"这个词的复数形式。它不是"skill"，是"skills"。这意味着我们讨论的不是单一能力，而是一整套能力体系——包括能力的定义方式、组织方式、调用方式、组合方式，以及能力之间的边界和协作。这就从"给智能体加个功能"上升到了"给智能体设计一套能力架构"的层面。我在实际做智能体相关项目的时候，踩过最多的坑恰恰就在这个层面：单个skill写得漂漂亮亮，一组合起来就互相打架，或者调用时机完全错乱。

所以这篇内容我想聊的，不是某个具体的skill怎么写，而是围绕"agent-skills"这个核心，把智能体能力体系的整体设计思路、核心细节、实操落地和常见坑，从头到尾捋一遍。适合正在做智能体应用开发的同学、想把大模型能力工程化的团队，以及那些已经写过几个skill但总觉得"哪里不对劲"的实践者。我会尽量用大白话把原理讲透，同时给出可以直接抄作业的结构和参数，让你看完就能动手。

2. 智能体能力体系的整体设计与思路拆解

2.1 为什么不能把智能体做成"一个万能函数"

很多人刚开始做智能体，思路是"我把所有能力都塞进一个超级prompt里，让模型自己判断该干嘛"。我早期也这么干过，结果就是：prompt越写越长，模型开始"精神分裂"，明明该调用工具的时候它在瞎编，该直接回答的时候它又去调工具。这个问题的根源在于，你把"能力选择"和"能力执行"这两件事混在了一个黑盒里。

agent-skills这套思路的核心价值，就是把能力显式地拆出来，变成一个个独立、可描述、可调用的单元。这样做的好处有三个层面。第一是可控性：每个skill有明确的输入输出契约，模型只需要判断"当前任务该用哪个skill"，而不需要在一个巨大的prompt里同时完成理解和执行。第二是可维护性：某个skill出问题了，你单独改它就行，不会牵一发动全身。第三是可组合性：多个skill可以像积木一样拼起来，完成单个skill搞不定的复杂任务。

打个比方，这就像餐厅后厨。一个万能函数式的智能体，相当于让一个厨师既负责点单、又负责切菜、又负责炒菜、还负责结账，忙起来必然出错。而agent-skills的思路，是把后厨分成配菜、炒锅、凉菜、打包几个工位，每个工位有明确的职责和交接标准，主厨（也就是调度层）只负责根据订单决定走哪条流水线。这个类比我觉得特别贴切，因为智能体的调度层本质上就是个"派单员"。

2.2 能力拆分的粒度：拆太细和拆太粗都是灾难

拆分粒度是设计agent-skills时第一个要拍板的事，也是最容易拍错的事。我见过两种极端。一种是拆得太细，比如把"读取文件"拆成"打开文件""读取内容""关闭文件"三个skill，结果模型为了读一个文件要连续调用三次，中间任何一步出错整个链路就断了，而且token消耗翻倍。另一种是拆得太粗，比如一个skill叫"处理用户请求"，这跟没拆一样，模型还是不知道该干嘛。

我的经验是，按"用户可感知的完整动作"来拆。什么叫用户可感知的完整动作？就是这件事做完之后，有一个明确的结果产出，而且这个结果是可以独立验证的。比如"查询天气"是一个完整动作，产出是天气数据；"发送邮件"是一个完整动作，产出是发送成功或失败的状态。而"打开文件"不是完整动作，因为它没有独立的结果产出，它只是"读取文件"这个完整动作的一个内部步骤。

具体到参数上，我一般会控制单个skill的职责范围在"一次工具调用能完成"到"三次工具调用能完成"之间。超过三次的，考虑拆成两个skill；少于一次的（也就是纯逻辑判断），考虑合并进调度层或者直接让模型在推理里完成。这个粒度实测下来最稳，既不会让调用链太长，也不会让skill太臃肿。

2.3 调度层与执行层的分离：这是整套体系的骨架

agent-skills能不能跑顺，关键看调度层和执行层有没有分干净。调度层的职责只有一个：根据当前上下文，决定下一步调用哪个skill，以及传什么参数。执行层的职责也只有一个：拿到参数，老老实实执行，返回结果。这两层绝对不能互相渗透。

我踩过的一个典型坑是：在skill的执行逻辑里写了"如果参数不对就自己猜一个"。这看起来是"智能"，实际上是灾难。因为一旦执行层开始"自作主张"，调度层就失去了对全局的掌控，出了问题你根本不知道是调度错了还是执行错了。正确的做法是，执行层发现参数不对，直接返回一个明确的错误，让调度层决定是重试、换skill还是向用户澄清。

这个分离带来的另一个好处是可测试性。执行层的每个skill都可以单独写单元测试，给定输入验证输出。调度层则可以用模拟的skill返回值来测试决策逻辑。两层分开测，问题定位效率能提升好几倍。我在一个项目里就是因为坚持了这个分离，把一个原本要排查两天的bug在半小时内定位到了调度层的参数映射错误。

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

3.1 skill的描述怎么写才能让模型"一看就懂"

skill的描述（description）是模型决定要不要调用它的唯一依据，所以这个描述的质量直接决定了整个体系的准确率。我见过太多人把描述写成"这个skill用来处理XX"，这种描述对模型来说信息量几乎为零。好的描述应该包含四个要素：做什么、什么时候用、输入是什么、输出是什么。

举个例子，一个查询订单状态的skill，差的描述是"查询订单"。好的描述是："根据订单号查询订单的当前状态，包括待付款、已付款、已发货、已完成、已取消五种状态。当用户询问某个订单现在怎么样了、到哪了、有没有发货时使用。输入为订单号字符串，输出为状态码和状态描述。"你看，这个描述里把触发场景（用户问订单怎么样了）和边界（五种状态）都讲清楚了，模型判断起来就准得多。

还有一个细节是描述的用词要和用户的自然语言对齐。模型是靠语义匹配来决定调用的，如果用户说"我的包裹到哪了"，而你的描述里只有"订单状态查询"，匹配度就会打折扣。我的做法是在描述里把常见的同义表达都列进去，比如"包裹、快递、订单、货"都写上。这不会让描述变得冗长，反而能显著提升召回率。实测下来，加了同义词的描述比不加的，调用准确率能高出百分之二十左右。

3.2 参数设计：类型、必填与默认值的取舍

参数设计是另一个高频踩坑点。核心原则是：能用枚举就不用字符串，能必填就不要给默认值，能给默认值就不要让模型猜。这三句话听起来简单，但每一条背后都有血泪教训。

先说枚举。如果一个参数只有有限的几种取值，一定要用枚举类型，并且在描述里把每个取值都列出来。比如"操作类型"这个参数，取值是"创建、查询、更新、删除"，你就要在描述里写清楚这四个值分别代表什么。我见过有人用字符串类型让模型自由发挥，结果模型传了个"新建"进来，而代码里判断的是"创建"，直接匹配失败。枚举能从根本上杜绝这类问题。

再说必填和默认值。一个参数如果是必填的，就在schema里标required，让模型知道不传会报错。如果它有合理的默认值，就在描述里写明"不传时默认为XX"。最怕的是那种"看起来可选实际上必填"的参数，模型不传，执行层报错，调度层又不知道该怎么补，整个链路就卡住了。我的经验是，宁可多设几个必填参数让模型多问一句，也不要设一个模糊的可选参数让模型瞎猜。多问一句用户最多觉得啰嗦，瞎猜一次用户可能就直接不信任这个智能体了。

3.3 错误处理：让skill"优雅地失败"

skill执行失败是常态，不是异常。网络会抖、接口会挂、参数会错，这些都是必然会发生的。所以错误处理的设计，直接决定了智能体是"能用"还是"好用"。我的做法是把错误分成三类，每类有不同的处理策略。

第一类是可重试错误，比如网络超时、接口限流。这类错误执行层返回一个明确的"可重试"标记，调度层看到后自动重试，重试次数一般设2到3次，间隔用指数退避。第二类是参数错误，比如订单号格式不对。这类错误执行层返回具体的错误原因，调度层根据原因决定是让模型重新提取参数，还是向用户澄清。第三类是业务错误，比如"订单不存在"。这类错误不是bug，是正常的业务结果，执行层直接把它作为正常返回值返回，调度层据此组织话术告诉用户。

这里有个关键细节：错误信息要结构化，不要只返回一个字符串。我一般会返回一个包含error_type、error_message、retryable三个字段的对象。error_type用于调度层做分支判断，error_message用于给模型或用户看，retryable用于决定要不要重试。这样调度层的逻辑就非常清晰，不用去解析字符串。这个设计我在多个项目里复用，每次都能省下大量调试时间。

提示：千万不要在skill里吞掉错误然后返回一个"假成功"。这会让调度层基于错误的信息做决策，问题会越滚越大，最后排查起来极其痛苦。

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

4.1 从零搭建一个skill的标准流程

假设我们要给一个智能体加一个"查询物流"的skill，完整的流程是这样的。第一步，定义skill的元信息，包括名称、描述、参数schema。名称用英文小写下划线，比如query_logistics；描述按前面说的四要素写；参数schema用JSON Schema格式定义，包含tracking_number这个必填的字符串参数。

第二步，实现执行逻辑。这里的关键是把执行逻辑和调度逻辑彻底分开。执行逻辑就是一个纯函数，输入是参数对象，输出是结果对象。它不关心是谁调用的、为什么调用，只负责把活干完。我一般会把这个函数放在独立的模块里，方便单独测试。

第三步，写单元测试。给定一个合法的运单号，验证返回结构正确；给定一个非法运单号，验证返回的是参数错误；模拟网络超时，验证返回的是可重试错误。这三类测试覆盖了大部分场景，写完心里就有底了。

第四步，注册到调度层。调度层需要知道这个skill的存在，包括它的元信息和执行入口。注册的方式取决于你用的框架，但核心就是把元信息喂给模型，把执行入口挂到调度逻辑上。

第五步，端到端测试。用真实的用户话术去测，比如"帮我查下这个快递到哪了"，看模型能不能正确提取运单号并调用skill。这一步最容易暴露描述写得不到位的问题，因为模型的理解和你的预期往往有偏差。

4.2 参数提取的准确率怎么提上去

参数提取是实操中最容易掉链子的环节。用户说"帮我查下昨天那个快递"，模型需要从中提取出运单号，但运单号根本不在这句话里，它需要从上下文里找。这种"跨轮次参数提取"是准确率的重灾区。

我的应对策略有三个。第一，在skill描述里明确写出参数的来源，比如"运单号通常出现在用户的上一条消息或当前对话的上下文中"。第二，在调度层的prompt里强调"如果参数不完整，先向用户询问，不要猜测"。第三，对于高频场景，做一个参数缓存，把用户之前提供过的信息存起来，模型提取不到时可以从缓存里补。

还有一个技巧是给参数起一个语义明确的名字。比如tracking_number就比number好，因为模型看到tracking_number就知道这是运单号，看到number还得猜。名字本身就是一种提示，这个细节很多人忽略，但实测下来对准确率有实实在在的帮助。

4.3 多skill协作的编排方式

单个skill跑通之后，真正的挑战是多skill协作。比如用户说"帮我查下快递，如果还没到就帮我改下收货地址"，这需要先调查询物流的skill，根据结果判断要不要调修改地址的skill。这种条件分支的编排，有两种实现方式。

一种是让模型自己编排，也就是把两个skill都注册进去，让模型根据查询结果决定下一步。这种方式灵活，但稳定性差，模型有时候会跳过查询直接改地址。另一种是在调度层写显式的编排逻辑，比如用一个状态机来管理流程。这种方式稳定，但灵活性差，遇到没预设过的场景就抓瞎。

我的经验是混合使用：对于高频、固定的流程，用显式编排保证稳定；对于长尾、多变的场景，让模型自由编排。具体做法是在调度层的prompt里给出"推荐流程"，但不强制，模型可以按推荐走，也可以根据实际情况调整。这样既保证了主流程的稳定，又保留了应对意外的能力。

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

5.1 模型不调用skill或者乱调用skill怎么办

这是最高频的问题，没有之一。表现是：该调用的时候不调用，不该调用的时候乱调用，或者调用了错误的skill。排查这个问题，我一般按下面的顺序来。

先看描述。把skill的描述单独拿出来，问自己：如果我是模型，看到这段描述，能准确判断什么时候该用吗？如果答案是否定的，那就是描述的问题，回去改描述。再看参数。参数schema是不是有歧义？必填项是不是标清楚了？枚举值是不是列全了？参数问题也会导致模型犹豫。最后看调度prompt。调度prompt里有没有明确说明"优先使用skill而不是自己编造"？有没有给出调用示例？很多时候加几个few-shot示例，问题就解决了。

我整理了一个速查表，遇到调用问题时按这个顺序排查，基本能覆盖九成的情况。

5.2 skill执行超时和并发冲突的处理

skill执行超时在涉及外部接口的场景里很常见。我的处理原则是：给每个skill设一个超时时间，超时后返回可重试错误，由调度层决定是否重试。超时时间一般设5到10秒，太短容易误判，太长会拖垮整个响应。如果某个skill经常超时，那说明它依赖的外部服务有问题，需要单独优化，而不是靠调大超时来掩盖。

并发冲突是另一个隐蔽的坑。比如用户连续发了两条消息，触发了两个skill同时执行，如果这两个skill都要写同一个资源，就可能冲突。我的做法是在执行层加一个简单的锁机制，同一个资源的操作串行化。对于读操作不加锁，对于写操作加锁。这个锁不需要很复杂，一个基于资源ID的内存锁就够了。实测下来，加了锁之后，并发导致的数据不一致问题基本消失了。

5.3 我踩过的三个印象最深的坑

第一个坑是skill的返回值太大。有个skill返回了一整页的HTML，结果token直接爆了，模型后面的推理全乱了。后来我强制规定，skill的返回值必须是结构化的精简数据，超过一定长度的内容要做截断或摘要。这个规定后来救了我好几次。

第二个坑是skill之间有隐式依赖。比如skill A的输出是skill B的输入，但我在描述里没写清楚，模型就经常先调B再调A，然后B因为拿不到输入而失败。后来我在描述里明确写了依赖关系，并且在调度层加了前置检查，问题才解决。

第三个坑是过度依赖模型的判断。我曾经天真地以为，只要描述写得好，模型就能百分百正确地调用skill。现实是，模型会有各种意想不到的失误。后来我在调度层加了一层"硬规则"，对于某些绝对不能出错的场景，直接用规则判断，不走模型。这层硬规则虽然不够灵活，但胜在稳定，关键时刻能兜底。

注意：skill的设计不是一劳永逸的，随着用户使用场景的变化，你需要定期回顾和调整。我一般每两周会看一次调用日志，找出调用失败率高的skill，针对性优化。

6. 能力体系的扩展与长期维护

6.1 skill的版本管理与灰度发布

当skill多起来之后，版本管理就成了必须面对的问题。我的做法是给每个skill加一个版本号，调度层注册的时候可以指定用哪个版本。新版本上线时，先灰度给一小部分流量，观察调用成功率和用户反馈，没问题再全量。这个机制看起来重，但当你有一个skill改动影响了线上几万次调用的时候，你会庆幸有这个机制。

版本管理的另一个好处是回滚方便。新版本出问题，直接把调度层的版本号改回旧版本就行，不用重新部署。我在一个项目里就是因为有这个机制，一次线上事故在五分钟内就恢复了，用户几乎无感知。

6.2 从调用日志里挖出优化点

调用日志是优化agent-skills的金矿，但很多人不看。我一般关注三个指标：调用成功率、平均调用耗时、参数提取准确率。调用成功率低的skill，去看错误分布，是参数问题还是执行问题；耗时长的skill，去看是哪一步慢，能不能优化；参数提取准确率低的，去看用户的实际表达和提取结果的差异，针对性补充描述。

还有一个进阶玩法是分析调用序列。把用户的一次完整交互里调用的skill按顺序列出来，看看有没有冗余调用、有没有可以合并的调用、有没有可以提前的调用。我通过分析调用序列，发现过一个skill其实可以在更早的时机调用，调整之后整体响应时间缩短了将近三分之一。

6.3 什么时候该新增skill，什么时候该合并

随着业务发展，你会不断面临"要不要加个新skill"的决策。我的判断标准是：如果一个新的完整动作出现了，而且它和现有skill的职责有明显区别，就新增；如果它只是现有skill的一个变体，就考虑扩展现有skill而不是新增。

举个例子，原来有个"查询订单"的skill，现在要加"查询退款"。如果退款查询的逻辑和订单查询高度相似，只是接口不同，那我会把它作为订单查询的一个参数（查询类型），而不是新增一个skill。因为新增skill会增加模型的判断负担，而扩展参数只是多了一个枚举值。反过来，如果退款查询涉及完全不同的流程和数据结构，那新增skill就是合理的。

这个判断标准我用了很久，核心逻辑就是控制skill的数量。skill不是越多越好，每多一个skill，模型的选择难度就增加一分。我一般会把skill总数控制在一个合理的范围内，超过之后就开始考虑合并和抽象。

7. 一些关于agent-skills的个人体会

做智能体能力体系这件事，我最大的体会是：它更像是一门工程手艺，而不是一门科学。没有放之四海而皆准的最优解，只有在具体场景下反复打磨出来的"够用解"。我见过太多人追求"完美的架构"，结果迟迟落不了地；也见过有人用最土的办法，把skill一个个手写、一个个测，最后跑得比谁都稳。

如果你刚开始做，我的建议是先跑通一个skill的完整链路，从描述、参数、执行、错误处理到调度，全部走一遍。这一个skill跑通了，后面的就是复制和微调。不要一上来就设计一个能容纳一百个skill的框架，那是给自己挖坑。等你手上有三五个skill在跑了，你自然就知道该怎么抽象、怎么扩展了。

还有一个心得是多和实际使用者聊。skill设计得好不好，最终是用户说了算。我经常去看用户的实际输入，很多我自以为设计得很好的描述，在用户的真实表达面前根本匹配不上。用户的表达是千奇百怪的，只有真正看过足够多的真实输入，你才能写出覆盖度够高的描述。

最后分享一个小技巧：给每个skill写一个"反例"。就是在描述里明确写出"这个skill不适用于什么场景"。这看起来是废话，但实测下来能显著减少误调用。因为模型在判断的时候，正向的"适用场景"和反向的"不适用场景"结合起来，边界会清晰很多。这个技巧我几乎在每个skill里都用，效果一直很稳。