企业官网建设流程全解析

1. “agent-skills”到底是什么——先把这个概念拆清楚

1.1 一个翻车案例让我重新审视“技能”

上个月在给一个客户做基于大模型的企业知识库问答 agent 时，我犯了个典型的错误：一股脑往 agent 里塞了十几个 API 工具，包括查天气、查汇率、算运费、查库存……结果系统跑起来之后，模型经常把工具搞混。用户问“上海到北京的运费是多少”，它先调了天气接口，然后煞有介事地给出一堆毫不相关的数字，最后告诉用户运费需要咨询客服。你说它错了吧，它流程走得挺完整；你说它对了吧，结果完全没法用。

后来我把这些工具砍到只剩三个，重新组织成真正的“技能”，效果立刻翻倍。这次踩坑让我意识到一个很重要的点：agent 的能力边界不在模型，而在你怎么把“工具”变成“技能”。

聊 agent-skills 之前必须先定义清楚。我这里说的 agent-skills，指的是一套能让大模型驱动的智能体“学会并执行特定任务”的能力封装，它通常包含自然语言描述、可执行的工具调用逻辑、输入输出的约束说明，以及对应的测试和纠错机制。换句话说，单个 API 只是原材料，技能是把这些原材料打磨成工作流之后，能被智能体真正稳定调用的完整能力。如果你最近在开发 agent 应用，一定对这样的场景不陌生：模型聪明是聪明，但让它稳定完成一个多步骤的真实业务任务，就总是差点意思。问题往往不在模型智商，而在你交给它的“能力单元”有问题。

1.2 技能、工具、插件：边界到底在哪

很多刚接触 agent 开发的朋友会问：技能不就是工具吗？不完全是。工具是一个狭窄的接口，技能是一套完整的、自洽的、可复用的行为模式。比如“查天气”是一个工具，但“安排一次周末露营计划”是一个技能——它在内部可以调用查天气、查地图、查装备清单等多个工具，并且知道按什么顺序调用、结果怎么组合、出错时怎么兜底。

插件这个概念的粒度就更大了，它通常指一套包含 UI、权限、依赖关系的完整软件包，常见于各种集成平台。技能则更轻、更聚焦，它不关心界面，只关心“模型需要什么能力来完成任务”。我做了一个很简单的对照表，方便大家快速区分：

举个生活化的类比：你不会因为家里有一把螺丝刀，就说自己拥有了家具安装技能。真正的技能是知道先拼框架、再上背板、最后固定铰链，知道螺丝拧到什么程度不会滑丝，知道装错了怎么拆。把这种“流程感”和“经验判断”封装起来，才叫技能。

说到这大家可能也反应过来了，agent-skills 更适合谁来用？两类人：一类是正在做 agent 应用开发的工程同学，想找一个更稳的能力组织方式；另一类是业务侧想把自己的领域经验沉淀成 agent 可调用能力单元的专家。前者关注技术框架，后者关注技能建模，但两条路最终会汇合在同一个问题上：如何让智能体稳定、可预期地完成业务任务。

2. 设计 agent-skills：从需求到可用的思考路径

2.1 别从“我能加什么功能”出发，从“任务完成为什么失败”出发

我在做技能设计时有个习惯，先跑 20 条真实任务，统计模型的失败模式，再决定要做哪些技能。很多团队反过来，先看模型平台支持哪些工具，再想能做什么功能，这种做法我强烈建议改掉。原因是：agent 在真实场景里的失败通常不是“缺一个接口”，而是“少了一段流程判断”。

举个例子。你做一个电商客服 agent，任务里有“查询订单物流”，模型经常犯的错是：用户给了订单号，模型却忘记了先去查询订单对应的快递公司，直接就调用物流查询接口，然后接口返回数据格式错误，模型一脸懵。这种情况下，你需要的不是一个查物流工具，而是一个“订单物流跟踪”技能：先把订单信息解析出来，查询快递公司，再调用物流接口，最后把多段物流轨迹整合成一句人话。

技能定义的第一原则：以任务结果为导向，而不是以接口功能为导向。每次新建技能之前，先问自己三个问题：这个技能要稳定完成什么结果？现在模型在哪一步容易出错？技能能把哪段容易出错的过程固化成确定性逻辑？如果这三个问题想不清楚，那我建议先别写技能，回去把任务流程再梳理一遍。

2.2 给技能划定边界：输入、输出、约束条件

一个高质量的技能设计，至少要写清楚四件事。我这里给一个我自己常用来检查的描述模板，你在设计任何一个新技能时都可以对着它过一遍：

• 技能名称：必须是名词短语，能概括这个技能在干什么，不要用比如“工具A”“方法B”这类模糊命名。名称起得好不好直接影响模型对技能的理解。
• 触发条件：模型在什么场景下应该使用这个技能，写清楚关键词和行为模式，最好带上一两个正例。
• 输入要求：需要哪些参数，参数格式、单位、必填可选，参数的默认值是什么，参数从哪里来。
• 输出规范：返回什么格式的数据，哪些字段是必须的，失败时怎么表达错误，是否需要对用户隐藏内部细节。

比较关键的一点是：输出规范一定要给模型一个“数据失败也按格式返回”的指令。否则模型在技能异常时经常会自己编一个结果，这是 agent 应用最危险的隐患之一。我在实际开发中还会额外加一条规则：所有技能必须返回一个状态字段，success 或 error，并且 error 时必须携带错误码和错误描述，这一步能省掉后期大量排查时间。

边界设计上还有一个容易被忽略的点：技能不要设计得“太贪”。一个技能只做一件事，做到极致。有些同学喜欢把相关的操作揉成一个技能，比如“订单管理与售后处理”，结果模型判断“这个订单异常，我要不要用这个技能？”，然后它犹豫半天，选择了别的技能。技能粒度过粗，等于把判断题出成了阅读理解，模型当然容易失分。

2.3 技能描述是与模型之间的接口，不是给人看的文档

我见过不少团队把技能描述写得像开发文档，动词、术语、细节堆一大堆，模型看起来特别费劲。要记住，模型的注意力有限，技能描述本质上是给模型看的“使用说明书”，不是架构文档。好的技能描述，第一句话就要告诉模型“什么时候用”，第二句告诉它“最后输出什么”，然后才是“具体怎么做”。

这里给一个对比。烂描述：“该接口用于调用内部订单系统查询订单信息，支持通过订单号查询订单详情，同时可通过订单号关联物流信息……”好描述：“当用户询问订单状态或物流进度时使用此技能，输入订单号，返回订单当前状态及最近一条物流记录。”后者读起来一气呵成，模型执行时跑偏的概率会低很多。

我在团队里经常说一句话：工具是给代码调用的，技能是给模型调用的。这段话要刻在脑子里。代码调用接口关心的是参数类型和返回字段，模型调用技能关心的是“我该不该用”“用了会得到什么”。所以技能描述里的措辞，不要用开发文档式的客观描述，多用业务场景式的指令表达。描述里可以适当加入第一人称视角，比如“当用户向你询问物流信息时”，让模型更容易代入执行场景。

3. 落地实现：搭一个可复用的 agent-skills 模块

3.1 目录与文件结构设计

技能的组织方式，我介绍一下目前比较主流的一种结构，灵感来自于社区经典的 Claude Skills 设计，现在很多开源项目也逐渐形成了类似约定：

skills/ 01-order-tracking/ SKILL.md main.py requirements.txt tests/

SKILL.md 是技能的说明书，用 Markdown 写清楚上面的触发条件、输入输出、使用方法。main.py 是技能的具体实现逻辑。requirements.txt 声明依赖，最好固定版本号，防止漂移。tests/ 放测试用例，后面我会专门讲测试怎么设计。

目录名最好带序号，方便 agent 在多个候选技能中快速理解优先级。序号本身也有语义，比如 01 表示核心能力，02 表示辅助能力，排序在前面的技能会被模型优先考虑。当技能数量涨到十几个以后，这套排序规则能显著降低模型选错技能的概率。

3.2 SKILL.md 是技能调用的说明书

我个人觉得 SKILL.md 是整个技能栈里最容易被低估的部分。很多团队随便写两行，结果模型根本不知道技能能干到哪一步。这是一个比较完整的模板，你可以直接参考：

# 订单物流跟踪 ## 何时使用 用户询问订单的物流状态、快递进度、包裹到哪了，或者主动提供订单号要求查询物流时。 ## 输入 - order_id: string, 必填，用户提供的订单号 - 可选：期望回复风格（简洁/详细） ## 输出 返回 JSON： - status: success | error - message: 给用户的自然语言结果 - logistics_events: 最近三条物流轨迹（时间+地点+事件） ## 执行步骤 1. 调用 get_order(order_id) 获取订单信息和快递公司 2. 调用 get_express(company, order_id) 查询物流轨迹 3. 如果步骤 2 返回错误，检查快递公司字段，尝试修正后再调 4. 整合结果，返回 message ## 注意事项 - 不要假定所有订单都有物流轨迹；生鲜订单可能在特殊时段无轨迹 - 物流状态为“已签收”时，务必提取签收人姓名 - 任何接口异常都返回 status=error，不要伪造数据

这样一个结构，模型读一遍基本就能学会在什么条件下调用，怎么传参，怎么处理异常。还有一个额外的收益：这套 SKILL.md 可以直接拿来做测试用例的基准，后面的 4.1 我会具体展开。

写 SKILL.md 的时候要刻意控制长度，我建议控制在 60 到 120 行之间。太短了描述不全面，模型用的时候会漏步骤；太长了模型的核心注意力会被稀释，反而记不住关键指令。这跟人看说明书一样，一百页的说明书很少有人读完还能记住重点。

3.3 把编排逻辑留在代码层，别让模型现场编

技能内部的调用逻辑，应该尽量把复杂的编排放进代码里，而不是让模型在 prompt 里临时编排。我举个反例：一个技能如果需要按顺序调用多个 API，有的团队就把这几个 API 都暴露给模型，让模型自己决定先调谁后调谁。这种做法在简单场景下能跑，但一旦上下文变长或者任务变复杂，模型大概率漏步骤。

更稳的玩法是把编排逻辑写在代码层。比如上面的物流跟踪技能，main.py 里直接实现“订单查询+快递公司识别+物流查询+消息组装”这条链，暴露给模型的只有输入 order_id 和输出 message。模型只需要决定“要不要用这个技能”，不需要关心技能内部的细节。这个思路其实就是把技能当作一个原子单元来使用，模型的思辨能力放在任务拆解和结果解释上，而不是放在低层的 API 调用序列上。

这样做还有一个明显好处：当第三方接口升级或某个步骤需要调整时，只改 main.py 就行，不需要动模型侧的任何东西。模型侧的技能描述保持稳定，意味着模型学到的行为模式不会频繁波动，这在生产环境里非常省心。

3.4 一个简单的实操示例：周末活动策划背后的两个技能

接下来看一个从零开始的具体例子。假设我要做一个周末活动策划 agent，需要两个基础技能：查周末天气和查附近公园。

查天气技能的核心逻辑可以这样写：

def get_weekend_weather(city): urls = [ f"https://api.weather.local/city/{city}?days=3" ] data = fetch_json(urls[0]) return { "status": "success", "weather": [ {"day": d["date"], "condition": d["condition"], "temp_low": d["low"], "temp_high": d["high"]} for d in data["daily"][:3] ] }

查附近公园技能的逻辑：

def find_nearby_parks(city, radius_km=5): parks = query_park_db(city, radius_km) return { "status": "success", "parks": [ {"name": p["name"], "distance_km": round(p["distance"], 1), "features": p["features"]} for p in parks ] }

然后给每个技能配一段简洁的 SKILL.md，比如天气技能的关键描述：

# 周末天气查询 ## 何时使用 用户提到周末出行、户外活动、是否需要带伞或增减衣物时使用。 ## 输入 - city: string, 必填，城市名 ## 输出 返回未来三天天气预报，包含天气状况和最高最低温度。 ## 注意事项 - 只有用户明确表达周末出行相关意图时才使用 - 如果用户只问“今天天气怎么样”，使用即时天气技能，不要用本技能

这个示例看起来简单，真正有价值的是设计思路：两个技能拆开、各管一件事，模型组合起来非常自然。用户说“周末想找个凉快的公园走走”，模型先调天气技能判断周六日温度，再调公园技能筛出周边选项，最后组装成一段建议。如果当初我把这两个功能揉成一个“户外活动推荐”技能，模型反而要在很多无关参数里做选择了。

4. 训练与验证：技能好不好用，测了才知道

4.1 测试用例：覆盖成功能路径，更要覆盖异常路径

技能上线前必须有一套测试集。除了覆盖正常调用路径，我强烈建议专门写异常路径的用例。所谓异常路径，包括：用户输入缺失、第三方接口超时、返回数据结构变化、技能执行结果语义不对等。这些异常场景才是 agent 在真实环境中翻车的高发区。

针对上面的物流跟踪技能，测试集至少要有这几条：

测试的时候不要只看最终返回格式，还要看错误分支时的用户体验。agent 技能的错误返回，理想状态是给用户一个可以下一步操作的提示，而不是一句“系统错误”。比如接口超时时，返回“查询超时，请稍后再试或联系客服”，就比裸抛一个 exception 要好得多。

测试哪些内容需要持续迭代。我建议每两周回看一次线上日志，把真实用户的失败案例补充进测试集。测试集本身不是静态的，它是技能能力的体检报告，会随着你对业务的理解加深而越长越全。

4.2 自动跑分和人工回归怎么取舍

技能效果评估我建议用两层：第一层自动化跑分，第二层人工回归。自动化跑分适合监控改动是否引入回归，人工回归适合判断输出语义是否自然。我们之前吃过亏：把自动化指标调到 98%，实际用户体验还是不好，因为自动评分只检查格式，不会检查语气是否生硬、信息是否冗余。后来我们在自动跑分之外，每周抽 10% 的交互日志，专门看“用户对 agent 输出的不满意的反馈”和“agent 自己承认错误的情况”，这些信息比准确率更有价值。

人工回归不需要把每个 case 都过一遍，重点是看两类：一类是自动跑分通过但用户反馈差的，另一类是边界输入，比如超长文本、口语化表达、含有错别字的输入。真实用户永远不会按你设计的标准姿势输入，人工回归的根本目的就是把模型和技能从“考场模式”拉回到“实战模式”。

4.3 技能版本的演进与管理

另一个容易被忽视的问题是技能版本。技能不是一次性写好就完了，随着业务变化和模型升级，需要持续调节。我的习惯是每次修改技能时先更新 SKILL.md，再更新代码，最后跑一遍全量测试集。如果改动涉及输入输出格式变更，还要检查所有引用该技能的 prompt 模板。这些步骤听起来繁琐，但正是它们防止了“上一个版本还能用，新版本直接崩”的尴尬。

版本管理上我建议用语义化版本号：主版本号变更表示输入输出格式不兼容，次版本号表示逻辑增强，修订号表示 bug 修复。每次发布在变更说明里标注清楚“模型侧需要感知的变化”和“纯代码层面的变化”，这个信息直接同步给上层编排逻辑的维护者。团队多人协作时有条件的话可以引入自动化 CI，跑完测试再合并，把人工检查的点降到最少。

5. 常见问题与避坑指南

5.1 技能没生效的三种典型情况

最常出现在工作群里的问题就是“技能没生效”，我总结了三种典型情况：

1. 技能描述没有被加载进上下文。这种情况发生在接入框架时把技能列表漏传了，或者上下文超过模型窗口，技能描述被截断。排查时先打印传给模型的完整 Prompt，肉眼确认技能描述是否在。
2. 模型选择了技能，但参数传错。多半是输入描述不清晰导致模型不知道参数来源。比如技能输入要求 user_name，但对话里用户从头到尾没报过名字，模型只能瞎填。解法是把技能接收参数设计成可以从上下文推导出来的值，同时给默认值，让模型即使拿不到精确值也不至于直接报错。
3. 模型调用了技能，但技能内部报错。这类错误往往出现在第三方接口上，外面包装得再漂亮，里面一个 request 超时，整个流程就断了。我的经验是技能内部必须做完整的异常捕获，不仅 try/except，还要给每个可能失败的点标注清晰日志，最好给错误码。错误码要设计成一看就知道是哪个环节出了问题，比如 ORDER_NOT_FOUND、EXPRESS_API_TIMEOUT，而不是一串数字。

这三类问题的共性根源是：模型、技能描述、技能实现三者之间的信息不对称。所以排查时不要一头扎进代码里看，先用“ Prompt 里有什么、模型收到了什么、技能返回了什么”三段日志对一遍，基本一分钟内能定位。

5.2 权限与安全：技能是系统敞开的门

技能能访问外部系统，本身就是给 agent 开的“门”。我见过一个团队给客服 agent 加了一个“订单金额计算”技能，结果技能定义里带上了内部数据库连接串，用户在对话里诱导模型输出技能源码，把连接串套走了。这个问题不是说几十行代码的问题，而是权限模型的设计问题。我的做法是：

• 技能代码里禁止硬编码任何密钥，一律从运行时环境变量读取
• 技能的运行环境与主应用隔离，网络策略最小化，只放行必要的外部端点
• 输入参数严格校验，过滤掉命令注入和路径穿越的常见 payload
• 所有对外调用必须有日志，方便出事时审计

敏感操作技能，比如退款、改地址、删除数据这类，必须增加二次确认环节。模型在调用这类技能前先向用户复述请求并请求确认，确认后再执行。这个设计不是为了防用户，而是防模型在幻觉状态下执行危险操作。算是给 agent 加一道保险栓，别嫌麻烦，真的出事的时候你会庆幸有这道流程。

5.3 多技能并发时的优先级与路由

当技能数量超过 10 个时，会出现一个新问题：模型经常选错技能。我建议从两个方向解决。一是做技能分组和路由，先让模型判断任务类别，再只暴露这一类下的技能，而不是一次性把所有技能都给出。二是给 SKILL.md 的“何时使用”增加排除描述，明确告诉模型哪些场景不要用它，这种负例往往比正例更有用。

我做过的最高纪录是 28 个技能同时在线，当时就是用分组路由撑起来的。分组规则直接写在系统提示词里，比如把技能分为“订单域”“商品域”“优惠域”，模型先判断用户问题属于哪个域，再加载对应域的技能描述。效果很稳定，推荐尝试。排除描述也很关键，比如一个“改签机票”技能，要明确写上“仅适用于已出票订单，预订未出票时不要使用”，否则模型会拿着它处理所有跟机票相关的问题。

多技能场景还有一个细节：给技能排序和分组的时候，把互斥技能放到不同组里，避免模型在同一组里做困难的二选一。比如“标准退货处理”和“生鲜品特殊退货”两个技能最好放在不同业务域下，模型先判断商品品类，再加载对应技能，显然比同时把两个技能亮出来让它选要稳得多。

我个人在实际操作中的体会是，agent-skills 最大的价值不是让模型变聪明，而是让工程团队能把业务经验沉淀成一系列稳定、可测试、可演进的能力单元。测试集和版本管理可以解决一半的问题，剩下的要靠你对业务场景的理解。最后再分享一个让整个流程更顺畅的小技巧：把技能开发当成一个独立于单一业务线的平台来维护，每个技能都有独立的负责人。这样当上层 agent 需要新能力时，不用重新造轮子，直接从技能仓库里查有没有可复用的模块。技能孤岛比数据孤岛更可怕，因为模型更容易被混乱的技能引入歧途。能读到这里的同学，你大概率已经遇到了类似的问题，不妨按这套思路把技能体系重新捋一遍，会比预想的简单。