企业官网建设流程全解析

1. 为什么这个时代需要“agent-skills”？

过去一年多，圈子里聊的从“大模型能做什么”慢慢变成了“大模型怎么稳定地做成一件事”。如果你亲手搭过Agent，多半遇到过这种尴尬：模型很聪明，但一到具体动作就飘，要不就是调工具时漏参数，要不就是步骤一多就开始瞎编。解决思路有很多，其中最让我觉得接近“根治”的，是“agent-skills”这套思路——它本质上不是给模型灌更多知识，而是把“做事的方法”沉淀成一套可复用、可组合的技能库。

“agent-skills”这个名字我第一次看到时，第一反应是“这不就是把Prompt模板换了个说法吗”。后来自己动手整理才发现，差得远了。Prompt模板是给模型念的“台词”，而agent-skills更像给Agent装配的“肌肉记忆”：它包含任务的触发条件、执行步骤、依赖工具、输入输出的约束，甚至失败后的回退方案。简单说，一个没有skills的Agent是个聪明但没经验的实习生，而有了skills之后，它才像一个按SOP办事、知道边界在哪的老员工。

这篇文章想聊的，就是我在实际项目里使用、设计、踩坑之后总结出的agent-skills落地经验。适合正在做Agent应用、想提升模型执行稳定性、或者准备搭建内部Agent平台的人参考。我会尽量少讲虚的，多放能直接用的结构、代码和判断标准。你把这套东西拿回去，不需要改模型、不需要上多贵的算力，先把技能库搭起来，Agent的可用性能上一个台阶。

我自己的体会是：Agent系统里，模型能力决定上限，但技能体系决定下限。只要下限够稳，产品就敢对外开放，这也是我后来把所有实验性Agent都重构出一层skills层的原因。下面我会从设计思路、技能结构、实操代码、评测方法、常见坑五个方面展开，带你完整走一遍。

2. agent-skills究竟是什么：从工具调用到技能编排

2.1 先分清：工具、技能、任务三者的层次

为了不把概念搞混，先给一套我常用的分层方式。工具（Tool）是最底层的能力单元，比如“查天气”“发HTTP请求”“计算MD5”，它是单一的、原子的，没有业务判断。任务（Task）是用户发出的一句话诉求，比如“帮我安排明天下午三点的会议”，它往往是模糊的、需要拆解的。而技能（Skill）正好卡在中间：它把多个工具串起来，加上判断逻辑、默认参数、异常处理，形成一套可以重复执行的能力。

举个例子。你有一个“发送会议邀请”的工具，入参是参会人、时间、会议室ID。但直接让模型调这个工具，它很容易漏掉“会议冲突检测”“跨时区换算”这种潜规则。而如果你封装出一个“会议安排技能”，这个技能内部定义了完整的执行链：先查忙闲、再选会议室、时区不一致时统一转成参会人本地时间、最后才发邀请并做结果校验。模型只需要说“我想开会”，技能层就会自动完成剩下的动作。

这就是agent-skills的核心价值之一：把“怎么做”从模型的不稳定推理中剥离出来，变成确定性代码或半确定性的流程编排。既然模型在自由发挥时容易出岔子，那就尽量压缩它自由发挥的空间，只让它负责“理解意图”和“选择技能”，而技能内部的路径是固定的、经过测试的。一层层往下收，系统的整体可靠性自然会上升。

2.2 为什么现阶段的Agent离不开技能库

我见过不少团队，早期方案是给模型配十几个工具，然后靠Prompt去约束“你先做A、再做B”。一开始demo效果很惊艳，一到真实流量就露馅。核心原因是模型对工具的调用受到上下文长度、注意力漂移、甚至Prompt位置的影响，步骤越多，中途出错概率越大。

技能库的另一个价值是沉淀经验。比如客服域里，“处理退款申请”这件事包含验证订单、核对金额、确认支付渠道、发审批通知等七八个环节，每个环节都有业务规则和边界条件。如果没有技能库，这些规则只能散落在Prompt里，改一处就要重新调整个Prompt，风险很大。而把它们固化成一个Skill，后续不管是换模型还是换工具实现，只需要改技能内部代码，对外接口完全不变。

还有个容易被忽视的好处——可测试性。Prompt怎么测？最多做几个case看回复质量。但技能是可以做单元测试的：给固定的输入，看输出是否符合预期、边界条件是否被正确处理、异常分支是否走到兜底逻辑。有了这层测试保障，Agent系统的回归成本大大降低。这也是我后来坚持在项目里引入skills层的最重要原因：不是为了架构好看，而是为了让系统真的能迭代、能收敛、能上线。

2.3 技能编排与编排器的关系

很多框架已经在做“路由”和“编排”，比如LangChain里的Router，或者各种Agent框架里的Planner。我的看法是：编排器负责“决策”，技能库负责“执行”。编排器根据用户意图，决定调用哪个技能、按什么顺序组合技能；技能内部则是相对封闭的执行单元，不关心上游是怎么选的。

这里容易踩一个坑：把技能编排逻辑全部写死在编排器里。比如在代码里if user_input包含“退款”就走退款技能，这样短期可行，但技能一多，编排器就变成一堆屎山。更合理的做法是给每个技能声明自己的触发条件和能力描述，让编排器通过推理或匹配来完成路由。这样新加技能时，不用动编排器，只注册技能描述就行。

我自己项目的做法是：给每个技能写一段不超过80字的描述，包含“解决什么问题、适合什么场景、需要哪些关键参数、不适用什么情况”。然后让模型读全部技能描述，结合用户输入选技能。一开始担心模型选错，实际跑下来发现，只要描述写得清楚，准确率能做到90%以上。剩下的模糊case，再配合一个“确认追问”机制兜底。

3. 搭建一套技能库的完整设计思路

3.1 从业务场景倒推技能清单

动手写代码之前，先把技能清单列出来。我推荐的方法叫“场景故事法”：找3到5个真实用户故事，模拟完整的交互流程，每走到一个需要外部能力或确定逻辑的节点，就记录一个技能候选。比如做一个人力资源问答Agent，场景可能是“员工问年假还剩几天”，那对应的技能就是“查询年假余额”和“计算年假折算”；场景也可能是“发起调薪申请”，那技能就得包含“构造调薪流程工单”。

清单列完之后做一个合并和裁剪。原则是：一个技能只做一件完整的事。不要造出那种“万能技能”，入参七八个、内部几十个分支，那样既难维护，也让模型很难判断什么场景该选它。宁可把复合流程拆成三个小技能，然后在编排层通过顺序组合来完成。比如“入职办理”拆成“创建员工档案”“分配默认权限”“发送欢迎邮件”三个技能，编排器按顺序调度。

裁剪的时候还要考虑技能的复用频次。如果一个技能只被一个场景用到，而且逻辑不复杂，可以先不封装，直接在流程里写条件分支。技能库的精髓是“高复用、低耦合”，不要为了封装而封装。

3.2 技能模板：描述、入参、执行体、兜底策略

不管用什么语言或框架，我建议每个技能都按四个模块来组织：描述（description）、参数定义（parameters）、执行体（executor）、兜底策略（fallback）。这四个模块缺一不可。

描述是给编排器或模型看的，不是给人看的。所以必须写得“对机器友好”：说清楚触发条件、适用场景、有什么限制。写描述有个技巧，多写反例。比如“此技能仅在用户主动询问余额时使用，不要在其他查询场景使用”，这样能显著降低模型误调用的概率。

参数定义最好用JSON Schema，不要用松散的口语描述。JSON Schema能约束类型、必填项、枚举值，模型生成入参的时候不容易漏字段。我之前遇到过Agent死活不传“申请日期”的情况，后来在Schema里把format写上、把必填标出来，问题立刻好了很多。

执行体是技能的核心，一般封装成函数或类。要注意的是，执行体不应该包含复杂的交互式对话逻辑，它的职责是“完成动作并返回结果”。判断标准很简单：如果一个技能内部还要跟用户来回确认好几轮，说明它不是技能，而是流程，应该拆开。

兜底策略是最容易被忽略却最重要的模块。技能执行失败时，返回一个友好且可理解的错误结构，包含错误码、可读信息、可执行建议。这样编排器才能根据错误码决定是重试、换技能还是转人工。

3.3 技能的状态管理与依赖处理

如果一个技能是纯函数式的，无内部状态，那是最理想的。但现实业务里，很多技能需要依赖上下文。比如“发送周报”技能需要知道本周完成的任务列表，这个数据来自上游的“任务汇总”技能。处理这种依赖，我推荐在编排器层面显式传递，而不要让技能自己去找上下文。

具体做法是维护一个上下文对象，编排器每执行完一个技能，就把结果写入上下文。后续技能通过参数引用上下文里已有的字段。这样做的好处是每个技能还是无状态的，测试时可以直接mock输入，编排器则负责串联数据流。

还有一类依赖是外部环境依赖，比如某个技能需要调用内部API，而内部API的鉴权方式、超时时间、重试策略各不相同。我的经验是把这些依赖收敛到技能内部，技能对外只暴露业务级参数。这样上层不需要关心某个技能走的是HTTP还是RPC，也不需要在编排层散落各种鉴权代码。

4. 实操从0到1：把技能逻辑跑起来的完整过程

4.1 技术选型：从轻量脚本到框架化

说到技术选型，先给一个结论：技能库不一定非要上重型框架，根据团队规模和系统复杂度来选。

如果你只是个人项目，或者在做概念验证，最简单的方案是用Python写几个函数，配上统一的装饰器注册，再写一个几十行的路由模块。伪代码大概长这样：

SKILL_REGISTRY = {} def skill(name, description, parameters_schema): def decorator(func): SKILL_REGISTRY[name] = { "name": name, "description": description, "parameters_schema": parameters_schema, "func": func, } return func return decorator @skill( name="calculate_leave_balance", description="计算员工年假余额，仅在用户查询年假时使用", parameters_schema={ "type": "object", "properties": { "employee_id": {"type": "string"}, "year": {"type": "integer"}, }, "required": ["employee_id"], }, ) def calculate_leave_balance(employee_id, year=None): # 这里写真实逻辑 ...

这个方案的好处是透明、可控、没有框架绑架，适合快速迭代。坏处是技能多了以后，调度、并发、缓存、监控都需要自己处理。

如果团队已经有Agent框架基础，或者技能数量超过二十个，建议做一层统一抽象。可以选开源的Agent框架作为底座，把技能以插件形式接入。我比较看重的框架能力有四个：技能版本管理、技能热更新、调用链追踪、灰度发布。前两个提升开发效率，后两个保证线上稳定。

4.2 一个真实技能从定义到上线的完整流程

拿“周报自动生成”技能来走一遍完整流程，这样更有体感。

第一步，定义技能描述。这个技能解决什么问题？它接收“本周任务明细”和“下周计划”，输出一段格式化周报文本。描述可以这样写：

“根据任务明细生成周报，适合用户要求汇总本周工作内容、生成周报、汇报进展时使用。此技能不包含任务查询能力，需要先通过任务查询技能获取本周任务列表。仅处理周报文本生成，不负责发送邮件或提交到系统。”

第二步，定义参数Schema。必须包含哪些字段？task_items是数组，每个元素里有title、status、completion_rate；next_week_plans是字符串数组。为了兼容不同上游，我把task_items设成必填，next_week_plans设成选填。

第三步，实现执行体。这一步相对简单，就是纯文本模板拼接，加上一点数据校验。关键点在于：如果task_items为空，要返回一个特定的错误码，而不是输出一份空洞的周报。因为如果周报内容太虚，用户一眼就能看出来是机器生成的，信任度会大打折扣。

第四步，注册到技能库，并在编排器里写一条样例路径。比如用户说“帮我生成一下这周的周报”，编排器先路由到“任务查询技能”，拿到task_items，再路由到“周报生成技能”，最后把文本返回给用户。

整个流程下来，我最大的体会是：描述和Schema的打磨时间应该占整体开发时间的一半以上。代码本身不难写，难的是让编排器在成千上万种用户表达中准确选中这个技能，并且保证入参不缺不漏。

4.3 与主流Agent框架的集成方式

现在很多框架都支持自定义工具或者技能。集成时有几个注意点。

第一是命名不要冲突。技能库的命名空间建议用“域_动作”的格式，比如“hr_query_balance”“hr_create_workflow”“wiki_search_page”。命名冲突轻则路由混乱，重则技能被随机覆盖，特别隐蔽。

第二是错误信息要标准。框架在技能报错时通常会把错误信息塞给模型，让模型自己决定怎么回复。所以技能返回的错误不能是“Exception: xxx”，而应该是结构化字段：error_code、message、suggestion。这样模型能看懂，代码也能处理。

第三是异步问题。很多真实技能涉及外部调用，必须用异步方式执行。如果你的框架不天然支持异步技能，建议自己在技能内部做并发控制，不要让一个慢技能阻塞整个编排。

我实际项目里做过一个粗略统计：引入技能库后，Agent端到端任务成功率从62%提到了81%。提升来源主要是两部分，一是技能内部固定逻辑减少了模型胡编的概率，二是错误能结构化返回后，很多失败场景可以自动重试或转人工，而不是直接对话中断。

5. 技能评测怎么做：量化指标与回归体系

5.1 评测维度：准确率、召回率、稳定性、延迟

技能库上线之后，怎么证明自己做的不是自嗨？我的建议是建立一套四维评测指标。第一维是路由准确率，即编排器把用户请求分到正确技能的比例。第二维是执行成功率，即技能被调用后，内部逻辑能跑通、返回业务成功结果的比例。第三维是结果稳定性，同一输入在相同条件下多次执行，输出是否一致。第四维是端到端延迟，从用户发起到收到最终结果的时间。

前两个指标其实是两回事。路由准确率关注“选没选对”，执行成功率关注“做没做成”。我见过很多项目的Agent能选对技能，但执行老失败；也见过技能本身没问题，但路由老选错的情况。分开测才容易定位问题。

稳定性这个指标最容易忽略。模型有随机性，但同一个技能应该尽量保证确定性。如果同一个技能跑五次，三次返回不同的结果，用户就会觉得“这东西不靠谱”。所以我在技能内部尽量用代码逻辑而不是模型生成来输出最终结果，只在极少数需要总结归纳的场景才让模型参与。

5.2 搭建一套技能回归测试集

技能库要敢迭代，必须有回归测试集撑着。我的做法是维护一个“skill_test.json”文件，里面按技能组织测试用例。每个用例包含：用户输入或参数、期望路由的技能名、期望结果（可以用匹配器做模糊对比）、允许的错误码列表，以及备注说明为什么写这个case。

测试集里至少要包含四类case：正常路径case、边界case、易混淆case和失败兜底case。正常路径是标准输入；边界case用来测空值、极长文本、异常格式；易混淆case是用来测路由的，比如“帮我算算我今年还剩几天年假”和“帮我看看我这两年都休了多少天年假”，看似相关，其实分别应该路由到“余额查询”和“休假记录查询”；失败兜底case则验证技能在外部依赖异常时是否能返回结构化错误。

回归测试可以做成定时任务每次发版都跑。跑完看两个维度：有没有新引入的失败case，以及之前失败的case是否被修复。不要求百分百通过率，但趋势必须是收敛的。如果某个技能的失败case连续几次都在增加，就应该暂停该技能的使用，先排查再说。

5.3 评测结果如何反馈到技能优化

评测不是为了得一个分数，而是为了指导下一步动作。我的优化路径一般是：先看路由准确率，低就先改技能描述和反例，实在不行再调整编排策略；再看执行成功率，低就查技能内部逻辑、外部依赖和参数Schema；最后看延迟，慢就做并发、做缓存、或者在技能内部加超时熔断。

这里分享一个踩过的坑：有个技能路由准确率一直高，但执行成功率低。查了很久才发现是技能内部调的API有频率限制，并发一高就返回限流。后来在技能内部加了本地缓存和降级逻辑，成功率一下就上来了。这个问题从评测指标上能看出来，但如果没有评测体系，光靠看日志找出根因会慢非常多。

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

6.1 Agent不调用技能，或者用错技能

这是最高频的问题。模型放着好好的技能不用，自己在那儿“凭空回答”。我的排查顺序是这样：先看技能描述是不是写得太泛，导致模型不觉得它专业；再看技能描述里是不是缺少“什么时候用”的触发条件；最后看模型对多个技能描述是不是产生了混淆。

如果描述已经很明确，还是不调用，那就要检查你的编排器。有些编排器是先把用户输入做意图分类，再按分类映射到技能。如果意图分类本身不够细，技能就永远不被选中。这时候与其反复调Prompt，不如在编排器里加一个“路由置信度”阈值，低于阈值时，向用户反问：“你是想查余额还是看记录?”

还有一个特殊情况：模型调用了技能，但传的参数不对。常见原因用上了错误的字段名，或者格式不对。我的建议是，在JSON Schema里不要只写字段名，最好每个字段给一个中文注释说明含义，再给一两个示例值。模型看到示例后，参数生成的准确率会明显提升。

6.2 技能执行成功但结果不满意

技能“做成功了”但用户不满意，这种问题最让人头疼。先确定一个原则：技能的成功定义不是“跑通代码”，而是“解决用户问题”。所以返回结果一定要有用户视角的校验。

我之前做过一个订会议室技能，代码逻辑完全正确，会议室也订上了，但用户就是觉得体验差。后来仔细分析才发现，技能返回的是“会议室已预订，会议ID为12345”，但用户当时想知道的是“是否和老板的会冲突”。你返回了结果，却没法打消用户的疑虑。解决办法是在技能内增加一个“关联信息查询”的可选参数，当用户提到“冲突”时，自动附带查询相关日程并做出提示。

类似的案例还很多。核心教训是：技能的执行体不应该只关注动作完成状态，还要关注“如何呈现结果才能让用户获得完整信息”。一个优秀的技能，在返回成功的同时，应该把用户关心的上下文也带回来。

6.3 技能数量膨胀后，编排器怎么扛住

技能从几个涨到几十个的时候，编排器迟早会遇到性能或准确率问题。因为每次路由都要把几十个技能描述塞进上下文，既浪费token，又让模型更难做选择。我的解决方案是给技能做“分层路由”。

第一层给技能打标签，比如“查询类”“写入类”“计算类”“通知类”。先根据用户输入判断大类，再在大类内部选择具体技能。这样每次路由只需要面对五六个候选技能，准确率和速度都会好很多。第二层是在技能描述里标注“关联技能”，当一个技能被选中时，把关联技能也带上，方便模型做组合调用。

还有一个细节：描述越长的技能，模型越容易记住。但也不要为了排序而可以加长描述，因为长描述会稀释关键信息。理想的描述是70到120字之间，重点信息前置，反例补充在后。

6.4 一个排查技巧：全链路日志里加技能调用地标

Agent系统排查问题，最怕的就是黑盒。我的习惯是给每个技能的执行体入口和出口都打上结构化的日志，包含技能名、入参、出参、耗时、错误码。这样一个请求从进来到出去，日志就形成了一条完整的技能调用链。

有一次排查用户投诉“明明让Agent查了金价，回复却说没有权限”，我看日志发现技能调用链根本没有“金价查询”的记录，说明编排器压根没往那个技能路由。于是我把排查重点从前端逻辑挪到路由策略上，问题很快定位。所以给技能日志做“地标”，比事后猜Agent的随机行为要高效得多。

7. 对agent-skills未来的一点个人判断

技能库这个方向，我判断还有很长一段路可以走。短期内的趋势是技能共享生态，团队之间、甚至公司之间把通用的技能封装好，像积木一样互相拼装；中期来看，技能会跟评测体系更深度地绑定，没有评测的技能不允许上生产；长期来看，技能可能不再只是“代码函数”，而会包含更复杂的数据飞轮，通过调用数据持续优化技能本身的表现。

我最近在尝试的方向，是把技能库做成“半自动生成”的：给出一段示例对话，让大模型自动提炼步骤、参数和边界条件，生成一个技能草稿，再人工审核后进库。这个流程虽然还不够成熟，但已经帮我省了不少时间。

如果你正在做Agent相关的事，我的建议很简单：先别急着追模型版本，先把技能库这层功夫练扎实。它不性感，不热闹，但它是把大模型从“玩具”变成“工具”的那道关键工序。我自己的实践反复证明这一点：模型进步很重要，但更重要的，是你用什么方式让模型稳定地解决问题。agent-skills这条路，值得认真走。