企业官网建设流程全解析

"agent-skills"这个名字，我在第一次看到的时候也愣了一下。它不像某个具体框架或者某个平台的SDK那么直观，但它近几年在AI代理应用里被反复提及，几乎成了搭建可靠Agent的默认底座。我自己经历了一个从"把所有能力塞进一段提示词"到"把能力拆成一个个可注册、可调度、可评估的技能模块"的转变，回头再看，这个转变本身才是让代理从Demo走向生产的关键。这篇文章想把我整理技能库、设计技能边界、构建技能评估体系过程中的经验完整写出来，完整到你可以直接照着搭一套属于自己的代理技能体系。

这篇文章适合已经在接触大模型应用开发，或者正在用Agent框架写自动化任务的开发者。如果你现阶段只是写写脚本，还没有被"代理乱调用工具""提示词越写越长但效果越来越差"这类问题折磨过，那正好可以先看看正确的组织方式长什么样。

1. 为什么代理应用不再靠"大提示词"而靠技能库

1.1 从单体提示词到技能模块的演变

早期做LLM代理功能的时候，很多人的第一反应是把所有指令全部写进系统提示词里，比如"你是一个助手，你可以做以下几件事：当用户查询天气时调用天气接口，当用户需要计算时调用计算器……"，再配上一大堆详细步骤。一开始效果还行，但随着功能增多，提示词会膨胀到几千甚至上万字，问题就接踵而至。

首先是命中率不稳定。模型在超长上下文里经常漏掉某些指令，尤其是藏在提示词中后段的工具调用说明，经常被忽略。其次是维护成本失控。每次加一个新能力，都要重新调整提示词结构，改一处就可能导致其他能力表现退化。我在一个模拟客服项目里就吃过这个亏：只是给提示词加了一个"兜底转人工"的逻辑，结果AI连最基本的订单查询都不触发了。

把能力拆成技能库之后，提示词反而变短了。代理只需要知道"当前场景有哪些技能可用、每个技能是干什么的"，具体怎么执行、执行边界在哪里，全部由技能模块自己负责。这其实就是把传统软件工程里的模块化思想搬到了LLM代理里，让"提示词+工具"这种松散耦合变成更可控的"意图+技能"结构。

1.2 agent-skills 到底是"工具"还是"动作"？

很多人在拆技能的时候会纠结一个概念问题：技能和工具（Tool）、函数调用（Function Calling）到底有什么不同？我个人的定义是：工具是逻辑层面的具体能力，比如"查数据库""发HTTP请求"；而技能是在工具之上封装的、面向目标和场景的可复用动作单元。

举个例子，"发送邮件"可以是一个工具，但"给客户发送项目进度周报邮件"就是一个技能。它内部可能包含查项目状态、生成周报模板、替换占位符、调用邮件服务、记录发送日志这五个步骤，外面只暴露一个明确的输入输出接口。这种区别很关键，因为代理在规划复杂任务的时候，更擅长调用一个高层次的技能，而不是自己组合一堆原子工具。如果让代理每次都要自己规划"先查这个表、再调那个函数、然后再拼装结果"，出错的概率会指数级上升。

所以agent-skills的本质是给代理提供"既知其然又知其所以然"的行动单元：它告诉代理这个技能解决什么问题、什么时候应该用、输入输出长什么样，同时也封装了内部的复杂逻辑。

1.3 这个体系适合谁，不适合谁

如果是纯问答类应用，不需要复杂的工具调用，那技能库反而会显得笨重，直接写提示词更简单。但如果你的应用要连续完成多步骤任务、要接多个外部系统、要允许不同团队往同一个代理里加能力，那技能库就是刚需。

还有一种不适合的情况：你的代理任务高度固定，比如每天就执行一条固定流程，不需要动态规划。这时候把流程写死在代码里，比让代理去"理解"技能表再调用要可靠得多。技能库最大的价值在于面对非固定路径、非确定输入的场景时，保持既有灵活性又有稳定性。

2. 搭建技能库前的两个关键设计决策

2.1 技能粒度：函数的边界就是技能的边界

我见过不少第一次搭技能库的人，最容易犯的错误是技能粒度失衡。太粗的技能像一个"万能接口"，代理调用了它还得在内部做大量分支判断，本质上又回到了单体逻辑；太细的技能又退化成原子工具，代理每次要调用七八个才能完成一个小任务，推理负担极重。

我总结了一个相对合理的粒度判断标准：一个技能应当能独立完成一个"对用户或系统有明确价值"的最小闭环。比如"查询订单并返回格式化摘要"是一个闭环，"计算两个日期之间的工作日天数"也是一个闭环，但"解析用户输入的时间表达式"就不是闭环，它只是某个闭环里的一步。

在实际项目里，我会先列出代理最常遇到的20个任务场景，再为每个场景设计技能，然后检查有没有重复覆盖。重复覆盖不是说两个技能功能相同不能用，而是必须约定优先级和适用条件，否则代理会陷入选择困难。

2.2 技能描述的质量直接决定代理的调用准确率

这里我想强调一个容易被忽视的细节：技能描述的作用对象是LLM，不是人。你写技能描述的时候，不应该只想着"把这个函数说明白"，而要想着"让代理在什么状态下能一眼看出该用它"。

好的技能描述应该包含三个层次：触发条件（什么情况下适合调用它）、执行效果（调用后能完成什么）、约束条件（什么情况下不应该调用它）。约束条件特别重要，比如一个"生成SQL查询"的技能，如果不写"仅用于内部数据平台的只读查询，禁止执行写操作"，代理可能会在需要更新的场景里误调用它，造成风险。

我在某次测试里做过对比，同一个技能，描述从一句话扩展成包含触发条件和边界约束的三句话后，代理在50个测试会话里对该技能的误调用次数从9次降到了1次。这个实验很直接地说明：多花几分钟打磨技能描述，远比在提示词里反复强调"你要仔细选择工具"有用得多。

2.3 技能命名、注册和版本管理

技能命名也有讲究。我常用"动词+宾语"的模式，比如 get_customer_balance、send_approval_notification。这种命名对模型来说更加直观，也方便在日志里快速定位问题。技能注册的时候要给每个技能分配一个稳定的ID，不建议直接用函数名做ID，因为函数名可能随着重构改变，但技能ID最好保持长期稳定，这样历史日志和评估数据才能对得上。

版本管理方面，我比较推荐参照接口版本化的思路：技能的行为一旦有显著变化，就开启新版本，旧版本至少保留一个过渡期。因为代理的对话可能跨多个请求，如果中途技能行为变了，之前的状态就可能对不上。我在一个多轮会话场景里就碰到过，第一轮调用的还是旧版技能返回的结果，第二轮升级后代码已经切到新版本，两轮的数据格式不一致，直接把代理中间状态解析搞崩了。从那之后，凡是可能影响输出的改动，我都会走一次版本备案。

3. 一个可复现的 agent-skills 最小实现

3.1 技能定义的数据结构

我目前最顺手的做法是用JSON来定义技能元数据，再配合一个Python类来做执行入口。每个技能由三部分组成：元信息、验证逻辑、执行逻辑。下面是我常用的一套结构（脱去业务细节后的简化版）：

{ "skill_id": "customer_balance_query_v1", "name": "查询客户余额", "description": "当用户询问账户剩余金额、可用余额、欠费情况时使用。本技能只支持只读查询，不执行扣费或充值操作。", "parameters": { "customer_id": { "type": "string", "description": "客户唯一标识，可以从会话上下文中提取", "required": true } }, "output_schema": { "balance": "number", "currency": "string", "updated_at": "string" }, "version": "v1", "status": "active" }

执行入口我一般用一个Python类来承接：

from typing import Any, Dict class BaseSkill: skill_id: str = "" description: str = "" def validate_input(self, params: Dict[str, Any]) -> Dict[str, Any]: """参数校验，返回清洗后的参数，抛异常则终止调用""" return params def execute(self, params: Dict[str, Any], context: Dict[str, Any]) -> Dict[str, Any]: """执行技能逻辑，返回符合 output_schema 的结果""" raise NotImplementedError class CustomerBalanceQuerySkill(BaseSkill): skill_id = "customer_balance_query_v1" description = "查询客户余额，只读操作" def execute(self, params, context): balance = query_balance_from_db(params["customer_id"]) return { "balance": balance["amount"], "currency": balance["currency"], "updated_at": balance["updated_at"], }

这里有几个细节值得说。第一，validate_input和execute分开，是为了让代理在调用前先做参数清洗，避免脏数据直接进入业务逻辑。第二，execute接收一个context参数，里面放着会话状态、用户身份、环境信息，技能内部可以根据这些信息做权限判断，而不是只依赖代理传过来的参数。

3.2 注册中心与动态加载

技能定义好之后，需要一个注册中心来统一管理。注册中心的核心功能是：保存技能元数据、支持按关键词搜索、支持按状态过滤（比如只让active状态的技能对代理可见）。

我常用的实现方式很轻量，一个Python字典加一个文件扫描就够起步了。每个技能文件放在skills目录下，文件名即模块名，注册中心启动时自动扫描并加载：

import importlib import pkgutil import skills SKILL_REGISTRY = {} def discover_skills(): for module_info in pkgutil.iter_modules(skills.__path__): module = importlib.import_module(f"skills.{module_info.name}") for attr_name in dir(module): attr = getattr(module, attr_name) if isinstance(attr, type) and issubclass(attr, BaseSkill) and attr is not BaseSkill: instance = attr() SKILL_REGISTRY[instance.skill_id] = instance

注册中心还要维护一个"代理可见技能列表"。不能把所有技能都暴露给代理，否则当技能数量上来之后，模型在超长技能列表里做选择反而会出错。我一般会按业务域把技能分组，再根据会话的初始意图给代理只加载一个子集。

3.3 让代理学会按需调用：示例会话

搭好最小实现之后，最关键的一步是验证代理能不能正确地按需调用技能。我会做这样的一个示例会话来测试：

角色设定：代理是一个客服助手，可用技能包括：查询订单、查询客户余额、创建工单、发送通知。

用户输入："我想看看我账户里还有多少钱。"

理想动作序列：先判断这是查询余额的意图，然后调用customer_balance_query_v1技能，取出customer_id参数，返回余额。

如果代理调用错了技能，第一步要看错误发生在哪个环节。是意图识别错了，还是参数提取错了，还是技能根本不可见。这三种情况的处理方式完全不同，下面这张表是我排查时的常用对照：

我自己的经验是，超过七成的调用失败都出在技能描述和参数描述没说清楚，而不是底层执行代码有Bug。所以每轮测试后，我最先改的往往是元数据，而不是执行逻辑。

4. 技能评测与迭代：从能用到好用

4.1 评测集怎么构造

代理技能不能只靠手工点几个例子就上线，必须有可量化的评测集。我的做法是构造一个"技能调用评测集"，里面每一条样本包含四个字段：用户输入、期望调用的技能ID、期望的参数、期望的最终输出。

举几个典型的评测样本：

[ { "user_input": "我这个月的账单为什么比上个月多了80块？", "expected_skill": "billing_detail_query_v1", "expected_params": {"billing_month": "2025-04", "user_id": "ctx.user_id"}, "expected_output": "包含账单明细和差异原因摘要" }, { "user_input": "帮我把这批订单全部标记为已发货", "expected_skill": "batch_order_update_v1", "expected_params": {"order_ids": [], "action": "mark_shipped"}, "expected_output": "更新成功数量及失败列表" }, { "user_input": "你好", "expected_skill": "no_skill", "expected_params": {}, "expected_output": "普通问候回应" } ]

评测集的数量不用贪多，我一般保持每个技能10到20条样本，覆盖面比绝对数量更重要。关键要覆盖边界情况，比如参数缺失、用户表达模糊、多个技能都能解释的歧义输入。

4.2 常见失败模式与根因

持续跑评测集一段时间后，我总结出三种高频失败模式：

第一种叫"技能名称诱惑"。当技能名里带了业务关键词，而用户输入也恰好包含这些词时，代理会倾向于调用该技能，哪怕语义上并不匹配。比如用户说"我不想要订单了"，代理可能因为看到"订单"两个字就去调用查订单技能，而用户的真实意图是处理退单。针对这种情况，我通常在描述里加上否定约束："仅当用户希望查看已有订单信息时使用，不用于处理退款或退货请求。"

第二种叫"参数来源幻觉"。代理经常从用户原话里抓取参数，但如果用户没直接说，它就会自己编一个。比如某个技能需要的customer_id，用户没有在对话里给过，代理就从历史消息里硬找，找不到就推测一个。这很危险。我的对策是在参数描述里写明来源路径，比如"从context.user_profile中获取，不可凭空生成"，同时加一层validate_input的校验，发现可疑参数就拒绝执行并提示重新提问。

第三种叫"多技能优先级混乱"。两个技能都能部分满足用户需求，代理随机选了一个。比如"修改订单地址"和"查看订单物流"，用户在问"我的订单能寄到新家吗"时，两个技能都可能被选中。这需要在描述里写明区分关键词，比如前者强调"要求修改"，后者强调"查询当前配送状态"，同时可以在技能组里配置优先级，让描述更精确。

4.3 灰度替换策略

技能迭代不是改完就全量生效，我习惯用灰度策略。做法是：新版本的技能先不替换旧版本，而是让5%的用户会话使用新版本，其余继续走旧版本。跑一段时间（我一般观察三到七天），对比调用成功率、参数校验通过率、下游任务完成率这三项指标，都稳定再全量切换。

这个灰度过程里，日志要做好标记。每条调用记录都要带上skill_id和version，这样后续分析才能精确定位是哪一版技能产生了问题。我吃过一次亏，早期没有区分版本，一个技能调了几十次都没发现问题，后来一查日志，线上同时混着两个版本的代码，数据根本没法看到底是哪个版本出了问题。

5. 真实项目里踩过的坑

5.1 技能描述写了一堆，代理却不调用

我最早做技能库的时候，特别认真地把每个技能描述写得很长，各种细节都塞进去，结果代理反而不调用了。后来我才明白，描述过长会让关键信息被稀释。LLM在限定上下文中选择工具的行为，本质上是在做一种机制化的匹配，太长的描述反而让模型抓不住重点。

我的改进方式是把描述拆成两部分：核心触发描述控制在两到三句话，先把"什么时候用、什么时候不用"说清楚；然后把更详细的执行细节放到执行入口的代码逻辑里，让代理在做选择时只需要看精简版描述即可。这个改动让技能调用准确率又提升了一截。

5.2 技能互相干扰：命名空间的设计失误

有一次我做了两个技能，一个叫"发送站内通知"，一个叫"发送短信通知"。它们的场景明显不同，但代理经常在需要发站内通知的时候去调短信接口。排查了很久才发现，问题不在描述，而在技能ID的前缀和内部实现里引用了同一个公共配置模块，导致两个技能在注册中心里互相覆盖了部分配置。

从那以后我规定：每个技能必须完全独立命名空间，自己的配置、常量、模板都放在自己的目录里，不共享全局变量。哪怕两个技能确实要调用同一个底层服务，也通过服务层封装来做，不直接共用技能内部的模块状态。

5.3 当技能数量超过50个时，检索和路由怎么处理

技能库做到50个以上后，如果还把所有技能一次性暴露给代理，模型的选择准确率会明显下降。我试过一次塞100个技能给代理，结果简单场景都开始错乱。

后来我引入了"技能路由"的概念：在调用链上加一个轻量的路由层，先根据会话的初始意图和用户画像，从技能库里筛选出可能相关的10到15个技能，再把这个子集交给代理做最终选择。路由层可以是一个简单的分类流程，也可以是一个更轻量的分类模型。关键在于路由要"宁可多给不要漏掉"，漏掉一个相关技能比多给几个无关技能更致命，因为代理只要子集里还有正确选项，就有机会选对；一旦正确选项被过滤掉，就必然失败。

6. 把 agent-skills 做成一个团队协作资产

6.1 技能评审和文档规范

当团队成员都开始贡献技能时，就需要一套评审规范了。我的技能提交检查表包含这几项：技能有没有唯一的ID和版本号；描述里有没有写明触发条件和禁止场景；参数有没有标注来源和是否必填；输出有没有匹配预定义schema；有没有附上至少5条评测样本。

这五条看着简单，但能挡住绝大多数问题。我之前接手的某项目里，有个成员提交的技能连参数schema都没写，代理倒是也会调用它，但调用后经常因为参数类型不匹配返回异常，排查起来特别费劲。后来强制了评审流程，这类问题基本绝迹。

6.2 技能的自动测试和回归

有了评测集和评审规范之后，还缺一个自动化测试环节。我把技能评测做进了CI流程：每次有技能改动，就跑一遍全量评测集，任何一条样本的调用结果发生变化，都会拦截合并请求。这套做法对信心提升很大，因为改动一个技能时最怕影响其他技能的调用行为，自动回归恰好能暴露这种隐性耦合。

6.3 从技能库到技能市场的扩展

技能库成熟之后，很自然会往"技能市场"的方向走。团队内部可以搭建一个技能共享门户，每个技能挂上标签、说明、提交人和使用量数据。这样不同项目组可以直接复用已经验证过的技能，不必每个项目都重新实现一遍订单查询、余额查询这类通用能力。

我在一个多团队协作场景里试过这种方式，效果很明显：两个团队各自的代理系统，在共享了基础技能包之后，开发周期缩短了大约三分之一，而且因为技能是被多个项目反复验证过的，出问题的概率也低了很多。不过要留意一点，技能一旦被多个团队共用，变更流程就要更严格，最好建立技能变更公告机制，重大变更提前通知所有使用方。

最后再分享一个实际操作的小技巧：每次往技能库里加一个新技能，先不要急着接进主代理。单独起一个测试环境，只给代理挂这一个技能，然后用20到30条真实风格的用户输入去跑，确认调用率稳定在95%以上，再合并进主线。这样做看起来多花了时间，实际上省掉的是后续排查"到底是哪个技能引入的问题"的大把精力。技能库的维护，慢就是快。