企业官网建设流程全解析

1. 为什么我会关注 agent-skills：从一个跑不通的Agent说起

先交代一下背景。前阵子我手头有个活儿：给某内部系统做一个能自动处理工单的Agent。需求不复杂——把用户提交的工单分类、提取关键信息、调用几个内部接口、回复处理结果。代码写了一版又一版，模型用的是常用的对话模型，工具（函数调用）也配了一堆。结果跑起来之后，效果让我挺崩溃的：工具调用时灵时不灵，模型偶尔干脆不调用工具，直接开始"自由发挥"编答案；有的场景下它会反复调同一个工具，完全不看返回结果是否满足条件；换个字段提法，同样的指令立马跑偏。

我相信凡是做过实际Agent项目的人，看到这里都会有同感。当时我一度以为是模型能力不行，换了更大的模型也没明显改善。后来我认真复盘，发现问题压根不在模型身上，而在我给模型提供的"技能"描述太粗糙了。我让模型去调用工具，却没有把"什么时候该用这个工具""传入参数要注意什么""返回之后要检查哪些字段""异常情况怎么兜底"这些信息讲清楚。换句话说，我把模型当成一个靠名字就能理解工具的开发者，但它其实更像一个新来的实习生，你光告诉它"有电话用电话"，它是分不清什么时候该拨、拨通了说什么、对方不在怎么办的。

agent-skills 这个名字，核心思路就是解决这个问题：把Agent能执行的操作沉淀成一套结构化的、可复用的"技能描述"，让模型在推理的每一个节点都清楚自己手头有什么、能用什么、用的边界在哪。这篇博文我不会去贴某个特定框架的完整配置，而是围绕"技能"这两个字，把我实际搭建、调优、踩坑的经验拆开来讲。内容适合正准备从"玩具Agent"迈向"能稳定干活的Agent"的开发者，也适合已经在做工具调用但总觉得"时而聪明时而智障"的人参考。

2. agent-skills 到底在解决什么：从工具调用到技能封装的思路转变

2.1 模型为什么经常"不会用工具"

大模型本身是一个文本预测模型，它并不像传统程序那样有一个明确的函数注册表。工具调用的本质，是模型根据对话上下文和工具描述，生成一段特殊格式的文本，这段文本委托外部系统去执行真实动作。所以这里存在一个天然的信息断层：模型看到的工具描述只是一段文字，它只能靠这段文字推断"这个工具是干什么的、参数填什么、返回值意味着什么"。

如果工具描述写得像一份模糊的接口注释：

• 工具名：send_email
• 描述：发送邮件
• 参数：to, subject, body

模型拿到这种描述，几乎所有不确定的地方都要靠猜。比如：to 支持多个收件人吗？subject 空着会怎样？body 长度有没有限制？发送失败会返回什么错误？发送成功后要不要提醒用户？这一系列问题，模型不知道，于是它的行为就变得不可控：有时候它把参数格式搞错，有时候它绕过了工具直接生成"我已发送邮件"的假象。这不是模型笨，而是我们作为开发者没有把语境交代清楚。

2.2 技能封装与工具调用的层次差异

传统工具调用，我们做的事情是定义"能干什么"；技能封装，要做的事情是定义"在什么情况下干、怎么干、干完之后怎么处理"。可以类比成：工具是一台电钻，技能是一份"使用电钻打孔的操作规程"——不仅说电钻能打孔，还规定了什么材质用什么钻头、转速调多少、打孔前要标记位置、打完后要清理碎屑。

agent-skills 的精髓，是把下面这些信息全部揉进一段结构化的定义中：

1. 技能的触发条件：什么场景下模型应该考虑调用这个技能，什么场景下不该调用。
2. 前置校验规则：调用前检查哪些字段、哪些条件必须满足。
3. 参数规范：每个参数的类型、范围、格式、是否必填、默认值。
4. 执行过程中的约束：比如超时控制、重试策略、并发限制。
5. 返回值语义：正常返回的字段结构、错误码对应什么含义、哪些返回结果意味着需要进一步操作。
6. 后续动作建议：根据返回值，模型下一步应该继续调用别的技能、还是直接给用户回复、还是请求用户补充信息。

当你把工具描述升级成技能描述之后，模型不再是一个"只会翻工具清单"的人，而是一个"理解工作流程并知道怎么执行"的操作员。很多之前看起来是模型能力问题的情况，其实都是因为模型拿到的信息不足以支撑正确推理。

2.3 什么类型的 Agent 场景收益最大

基于我的经验，技能封装在以下三类场景中收益最明显：

• 多步骤复杂任务：比如工单处理、预订流程、数据清洗流程。这类场景需要模型在多个工具之间跳转，每个步骤的输出会影响下一步的选择。没有技能描述，模型很容易在某个中间步骤上犯迷糊。
• 高风险操作：比如删除数据、转账、发送对外消息。这类操作必须设置严格的触发条件和前置校验，宁可让模型多问一句，也不能让它鲁莽执行。
• 工具数量较多的场景：当工具超过二十个以后，模型从一大坨描述里准确挑选工具的能力会明显下降。技能封装相当于做了一个"目录索引"，让模型按场景检索，而不是在一堆平铺的描述里大海捞针。

3. 一次完整的技能定义：以"自动查天气并提醒带伞"为例

光讲概念肯定不够，我直接拿一个最简单的例子——查天气然后提醒用户是否带伞——把一条完整技能定义拆给大家看。这个例子虽然简单，但涵盖了技能封装的所有核心要素，方便理解后面更复杂的用法。

3.1 先看一个糟糕的版本

如果你只是给模型注册一个工具，描述大概长这样：

工具名：query_weather 描述：查询城市天气 参数：city（字符串，城市名）

实际跑起来会出现什么状况？我问"明天上海下雨吗，我用不用带伞？"，模型确实调用了 query_weather，但它只传了"上海"，没有传日期，因为描述里根本没提日期参数。返回结果只有"上海 晴 25°C"，模型看到没有雨，就直接回答"不用带伞"。问题是它查的是今天的天气，用户问的是明天——这就是技能定义不全导致的连锁错误。

3.2 一个好版本的技能定义

我建议把一条技能写成这种结构：

技能名称：query_weather_with_reminder 技能描述： 查询未来指定的日期范围内的天气情况，并根据降水概率给出是否需要带伞的建议。 仅在用户明确询问天气，或用户在计划出行、户外活动时考虑调用。 若用户没有提供城市名，主动询问用户所在城市；若用户没有提供日期，默认查询今天； 若用户询问的是明天或多天后，必须将日期参数显式转换为 YYYY-MM-DD 格式后传入。 参数： - city: string，必填。城市中文名称或拼音，示例：北京、shanghai。 - date: string，可选。查询日期，格式YYYY-MM-DD。不传时默认当天。 - granularity: string，可选。取值hourly/daily，默认daily。 返回值语义： - 返回字段 precipitation_probability 为 0-100 之间的整数； - 若该值大于等于 70，视为高降水概率，建议提醒用户携带雨具； - 若该值大于等于 40 且小于 70，视为可能有零星降水，提醒用户根据出行时间判断； - 若小于 40，提醒时不强调带伞。 后续动作建议： - 若查询日期与用户询问日期不符，需重新查询正确日期； - 若返回值为空或出现超时错误，告知用户"天气服务暂时不可用，请稍后再试"，不要编造天气数据。

看到区别了吗？糟糕版本只告诉模型"有锤子"，好版本告诉模型"什么时候抡锤子、用什么姿势、砸完看什么迹象"。这段描述写清楚之后，模型的工具选择准确率和参数填充完整率会明显上升，出现幻觉式回复的概率也会降低。

3.3 一个容易被忽视的关键点：把"判断逻辑"写进技能描述

很多人会问：带不带伞的判断逻辑，不是应该在代码里写死吗？为什么要把判断逻辑塞给模型？

我的答案是：看这个逻辑是确定性的，还是依赖上下文的。如果你已经拿到了降水概率，那么"概率大于70就提醒带伞"这个规则确实可以在代码里写成 if-else。但模型的价值在于"判断是否满足触发条件"以及"组织最终回复"，比如用户说"我今天要在户外跑五公里，你看天气行不行"，模型需要综合天气、时间、用户意图来决定怎么说。这部分逻辑无法用固定规则覆盖，写进技能描述可以引导模型做出合理的推理。

我在实际项目中采用的做法是把规则分两层：硬性规则写在代码里，比如参数格式校验、超时重试、错误码映射，这些不应该依赖模型；柔性引导写进技能描述，比如什么时候调用、根据返回结果如何组织话术、异常时如何措辞。很多团队一开始把所有规则都塞给模型，结果模型被一堆约束压得推理混乱；又有团队把所有逻辑都写死在代码里，结果模型变得死板，稍微换个表达方式就不知道怎么办。找到中间那条线，是做好 agent-skills 的核心平衡点。

4. 技能描述如何设计才能让模型真正"看懂"

4.1 描述的三大常见误区

在给我自己的项目做技能封装时，我总结出了新手最容易犯的三大误区。

第一个是描述过于简短。有些人觉得工具描述写个一句话就够了，反正模型能力强，能理解。但模型没有读心术，你不说清楚边界，它就倾向于自由发挥。更反直觉的是，给模型更多上下文通常会提升它的推理质量，而不是干扰它。

第二个是描述中混杂了相互矛盾的指令。比如技能描述里先写"仅在用户明确许可时调用"，后面又说"若用户表达出相关内容即可自动调用"，模型看到这种冲突表述，行为就会变得不稳定。我建议一条技能描述内的所有约束保持逻辑一致，如果要修改规则，从全局角度重写，而不是打补丁式叠加。

第三个是过度追求大而全。我一个新人阶段的通病是把某条技能描述写成了一篇几百字的小作文，恨不得把各种可能情况全塞进去。实际跑下来，过长的描述会导致模型在解析时失焦，反而忽视关键触发条件。我后来给自己定了一个经验标准：一条技能描述主体部分控制在150到250字之间，参数和返回语义另用结构化方式写，不用全堆进自然语言里。

4.2 优秀的技能描述应该具备哪些特征

结合这几个项目的实践，我总结了四条判断标准：

• 主谓宾明确：描述里要说得清"谁在什么条件下，通过什么方式，完成什么目标"。
• 触发条件与不触发条件同样重要：明确写"什么情况下不要调用"，比只写"什么情况下调用"更能约束模型。比如技能描述里加一句"若用户仅询问气温而无其他需求，不要附带建议"，就能减少模型多余的发挥。
• 参数说明要具体到示例级别：每个参数最好带一个真实示例，比如"city：北京、shanghai；若用户说'我家这边'，需要先明确城市名再查询"。这能大幅降低参数幻觉。
• 返回值要有"人话翻译"：模型在调用工具后通常需要根据返回值组织回复，如果你只告诉它返回JSON结构，它不一定知道每个字段意味着什么。把字段含义和常见取值翻译成"人话"，模型的后续行为会稳定很多。

4.3 从用户视角反向设计描述

还有一个很实用的方法，我称之为"反向设计"。在写一条技能描述之前，先不急着动笔，而是设想要让一个聪明的实习生拿着这份描述去执行任务。如果这个实习生看完描述后，能准确回答以下问题，那么这条描述基本合格：

• 什么时候应该用我？
• 什么时候不该用我？
• 该给我什么信息？哪些信息必须给我，哪些可以猜？
• 我返回的结果要怎么理解？哪些数据意味着"出问题了"？
• 我拿到结果之后下一步该干嘛？

这个"实习生测试"看起来土，但非常有效。很多时候我们写描述时是站在"系统调用者"的视角，只关注参数和接口；切换成"实习生"的视角之后，才会注意到上下文、边界、异常处理这些模型真正需要的信息。

5. 在真实项目里落地 agent-skills 的完整路径

5.1 技能目录怎么组织：按领域分还是按动作分

技能数量一多，目录结构就需要提前设计。我见过两种模式：按领域分（工单技能、数据分析技能、邮件技能）和按动作分（查询类技能、写入类技能、删除类技能）。

按领域分的好处是模型在特定场景下面对的技能集合较小，比如工单处理Agent只加载工单领域的技能，检索压力小、描述可以更聚焦。按动作分的好处是跨领域复用性强，例如所有场景的查询类技能共用一套参数规范和错误处理逻辑，模型更容易形成统一的调用范式。

我的建议是混合使用：从顶层按领域分组，组内按动作组织技能列表。实际在配置层面，可以把领域信息写进技能描述的前缀，比如"工单系统技能"，让模型在意图识别阶段就能锁定到正确的技能集合。如果你用的是那种允许动态加载技能元数据的框架，可以在意图初判之后再把对应领域的技能注入上下文，减少模型在大量无关技能里做选择的负担。

5.2 技能描述纳入研发流程：像写接口文档一样评审

很多人都没意识到，技能描述其实是一种需要维护的"产品资产"，而不是随便写写就完事的配置。我在团队内部推动过一个做法：技能描述必须经过和接口文档一样的评审流程。

具体来说，我的流程是三步：

1. 撰写者（通常是后端开发者或Agent开发者）先按业务方的真实需求起草技能描述。
2. 评审会上，由另一个人扮演"刁钻用户"，按照描述跑一遍对话，看描述是否能支撑所有合理的用户输入变体。
3. 上线后再根据实际日志，持续修正描述。

这听起来有点重，但Agent项目的调试成本远高于传统接口联调。你在描述阶段多花半小时，后面可能少调三天的模型参数。哪些技能描述频繁导致工具调用错误，哪些技能明明存在但模型一直不调用，这些都可以作为评审的输入。

5.3 一条务实的调试路径：从单体技能到技能编排

初学者在做技能封装时，容易一上来就设计一大套"技能编排图"，结果模型根本不按编排路径走，最后只能不停加约束。我的建议是先从单体技能开始：每个技能独立可测，输入输出边界清楚，模型能稳定触发、执行、处理返回值。这一步跑不稳，后面的编排全是空中楼阁。

等单体技能稳定之后，再开始做技能与技能之间的组合。比如"查天气技能"和"推荐穿搭技能"可以组成一个新的技能："天气穿搭建议技能"。组合规则需要描述模型如何在第一个技能返回的基础上选择合适的第二个技能，以及处理中间状态的逻辑。这个阶段通常需要给模型提供一份"步骤提示"，例如先调用查询天气技能，获得结果后再决定是否调用推荐穿搭技能。实测下来，这种渐进式路线比一上来就搞复杂编排的路线稳定得多，排错也要容易得多。

6. 实测结果与典型翻车场景复盘

6.1 技能封装前后的一组对比数据

我在某模拟项目里做了一个对照组实验，项目是"智能日程助手"，功能包括创建日程、查询日程、取消日程、查找空闲时间。工具数量一共8个。第一周我以普通工具描述运行，第二周我改成技能描述运行。为了让变量单一，模型、参数、系统提示词都没动，只改了工具描述文本。

主要变化如下：

这组数据不算严谨的科学实验，但趋势非常明显。值得注意的是参数完整率的变化，说明很多情况下模型不是不会填参数，而是你根本没告诉它需要填哪些参数。纯粹加大模型参数量，不如先把技能描述写到位。

6.2 三个典型的翻车场景与修复过程

场景一：模型反复调用同一个技能。用户问"这周有哪些会议"，助手调用查询日程技能后返回了空列表，但模型没有给用户返回"本周暂无会议"，而是再次调用同一个查询技能，来回循环七八次。原因在于技能描述里没有写"如果返回结果为空，直接告知用户，无需重复查询"。补上这个返回语义后，问题消失。

场景二：模型在错误的语境下调用技能。用户只是闲聊了一句"今天天气不错"，模型却把查天气技能调用了。我检查发现技能描述只写了"用户提到天气时调用"，却没有排除闲聊场景。后来我在描述中加了一句"仅在用户询问预报或需要基于天气预报做决策时调用"，准确率立刻上来了。

场景三：模型篡改参数。用户要求给某联系人发邮件，收件人字段是邮箱地址，但模型直接把联系人姓名填了进去，导致接口报错。修复办法是在参数说明里写清楚"若参数值是姓名而非邮箱地址，必须先在通讯录中查询转换为邮箱地址后再调用"。这就是把前置校验和转换规则写进技能描述的典型用法。

6.3 日志与可观测性：不能只靠肉眼调

技能封装之后，问题定位的难度反而可能上升，因为你不仅要追踪模型输出，还要追踪技能调用链路。我建议至少记录以下信息：

• 模型当前使用了哪条技能描述
• 模型生成了什么参数
• 工具实际返回了什么
• 模型根据返回值生成了什么最终回复
• 用户后续是否提出了修正性反馈

这样一旦出现行为偏离，就可以往回追：是模型没有正确理解技能描述？是描述本身有歧义？还是工具的返回值格式与描述不一致？我见过太多团队花了大量时间调提示词，最后发现是工具返回值里的一个字段名和描述里写的不一致，模型不是不听话，而是被错误的数据结构带偏了。

7. 技能描述与系统提示词：两者分工才是关键

7.1 哪些内容该放进系统提示词，哪些放进技能描述

很多初学者会把技能描述和系统提示词混为一谈，一股脑把所有说明都塞进系统提示词。这里有一个更合理的分工原则：

系统提示词负责"人的身份和全局规则"，比如"你是一个日程助手，回答要简洁，不要编造数据"。技能描述负责"具体操作和动作边界"，比如"查询日历时传入日期格式应该是YYYY-MM-DD，返回空列表时告知用户暂无日程"。系统提示词面向的是模型的人格和通用行为风格，而技能描述面向的是具体业务动作。

如果把技能细节全部写进系统提示词，场景一多就会产生信息冲突和上下文膨胀，因为系统提示词往往是每次请求都加载的。技能描述则可以按需加载，某些框架允许在意图识别后再动态注入相关技能描述，这样既保留了上下文空间，又能给模型提供足够的信息。

7.2 动态技能检索的必要性

随着技能库扩大，把所有技能描述一次性塞进上下文是不可行的。上下文窗口再大，模型也会在大量相似描述之间出现注意力分散。我在一个模拟项目中尝试过把五十条技能描述全部注入，结果模型频繁选错技能，准确率不到六成。

后来我引入了简单的技能检索机制：先用模型做一次粗粒度意图识别，输出一个领域标签，再根据标签加载该领域下的技能描述集合。实际操作里，我用的是基于关键词偏好加一个轻量级分类模型的方案，效果已经足够了。更复杂的方案还可以引入向量检索，把用户意图和技能描述做语义召回。但这一步不是必须的，技能数量在三十条以内时，分组按需加载就能拿到不错的效果。

8. 技能封装之后，Agent 调试的思维转型

8.1 从调模型参数到调技能描述

做完 agent-skills 重构后的最大感受是：Agent调试的重心从"钻研提示词魔法"转移到了"描述清晰、语义准确、边界明确"。模型本身当然重要，但大多数业务场景下，模型能力的瓶颈不在"懂不懂自然语言"，而在"你给它提供了什么信息组织方式"。

我自己调试时固定用一套排查顺序：先看技能描述是否覆盖了当前失败场景->再看返回语义是否解释清楚->再看参数说明是否有歧义->最后才考虑是不是模型选型问题。很多时候问题出在最前面两步，这一步排查顺序帮团队省下过大量无用的大模型参数实验。

8.2 版本管理与回归测试

技能描述不像普通代码，它作用于模型语义空间，改动之后的副作用往往不是立竿见影的。所以版本管理非常重要。我的做法是：

• 技能描述文件纳入Git管理，每条技能一个独立文件，字段包括技能名称、生效版本、描述文本、参数定义、返回语义。
• 每次修改必须写改动说明，记录"改动什么、为什么改、预期影响哪个场景"。
• 维护一份回归测试集，涵盖高频场景和过去踩过坑的场景，每次改动后先跑回归再上线。
• 线上用灰度发布策略，技能描述更新只对部分流量生效，观察日志后再全量放量。

这些做法看起来像传统软件工程的流程，但放到Agent项目里同样适用。技能描述就是Agent的一份"隐式代码"，它不直接执行，却决定了模型的行为边界，不认真管理一定会被埋下的坑教训。

在多个项目里走过一遍之后，我的体会是 agent-skills 背后代表的不是某个具体工具或框架，而是一种工作思维的转变：把模糊的"让模型学会干活"，变成"给模型提供清晰、完整、可验证的操作语境"。如果你现在也被工具调用不准、参数幻觉、行为反复折磨，我建议先从一条技能描述开始改起。你不需要一次性重写整个Agent，只需要找一条最常用、最让你头疼的工具，把它从"接口说明"改写成一份"操作手册"，然后跑上几十轮对话对比一下。这一步做完，你大概率会想回头把其他工具也全部重写——我已经替你们踩过这个坑了，效果确实值得。