构建Agent技能体系：从提示词堆砌到可复用能力封装

在上一个大版本迭代里，我发现效果最稳定的“Agent能力提升方式”其实是把日常高频复用的能力沉淀成标准技能包——而这件事恰恰是很多团队做AI应用时一直没做扎实的环节。搞了大半年实战，踩了不少坑，我把关于 Agent 技能的拆解、设计和落地经验整理出来，希望能帮到你。

先说清楚：这里说的“agent-skills”，不是让模型多背几段提示词，也不是随便丢几个函数接口让模型去调，而是围绕具体业务场景，把“意图识别、工具调用、过程控制、结果校验、异常兜底”这整套逻辑封装成一个个边界清晰、可复用、可测试的独立技能单元。真正跑起来之后，你会发现 Agent 的稳定性和专业性，几乎完全由这套技能体系的质量决定。

这套方法适合正在做智能客服、知识库问答、自动化报告生成、业务流程自动化，或者任何依赖大模型做复杂决策的开发者。哪怕你只是自己写了个小工具，想把“网上查资料、整理要点、生成摘要”这类动作做得更稳，也能直接用上。我会从为什么要做技能拆解、技能体系怎么设计、实操怎么一步步落地，再到常见坑怎么填，一层层说透。

1. 为什么你的 Agent 需要一套技能体系

很多团队一开始做 Agent，习惯把场景描述、业务规则、工具列表全部塞进一个超长的系统提示词里，让模型自己看着办。这种做法在小 demo 里很爽，但在真实业务里会迅速失控。我见过太多次这样的演进过程：第一阶段，单一任务还能稳定跑；第二阶段，加了十几个工具之后，模型开始频繁选错工具、搞错参数；第三阶段，面对稍微复杂的情况，要么漏流程，要么在关键步骤上凭空想象出根本不存在的结论，而且你还很难定位问题到底出在哪一环节。

1.1 LLM 的能力边界和技能封装的必要性

大语言模型本质上是一个“根据上下文预测下一个合理内容”的引擎，它在意图理解和初步方案生成上很厉害，但它不擅长做需要精确多步执行的事情。比如让它计算优惠券叠加后的价格，它可能会基于训练时见过的经验直接给一个答案，而不是老老实实把每一步算一遍——这就是 LLM 的“幻觉”和“惰性”来源。

技能封装的核心思路，就是把这些关键步骤从“让模型自由发挥”变成“让模型按照技能包定义好的流程去执行”。每个技能包里不仅写了“这个技能是干什么的”，还写了“输入参数是什么、中间过程怎么处理、什么情况下应该停下来、结果按什么格式返回”。模型只负责理解用户意图、选择合适的技能、填入参数，至于技能内部的推理和计算，完全由确定性代码接管。这样一来，本来“靠猜”的部分就变成了“精确计算”，准确率自然上去了。

1.2 从“插件列表”进化为“技能体系”

插件的思路是把能力平铺开，模型面对的是一个大而全的菜单，自己选。技能体系的思路则是把这些能力组织成有层次、有依赖关系、有执行协议的结构。一个成熟的技能体系，通常会包含指挥层、计算层、数据和工具层。

这样做相当于把“让一个聪明但散漫的实习生直接对客户做承诺”变成“让一个有经验的团队负责人把任务拆分好，再分给各岗位的专人去办”。每个岗位只做好一件事，接口清晰、差错可控。最终用户在对话里感受到的，就是这个 Agent 突然变得“靠谱”了很多——不再是闲聊式地回答，而是像模像样地“先把问题拆解清楚，再一步步把活儿干完”。

2. 技能体系的整体设计与落地路径

我刚开始做技能体系的时候，犯过一个典型错误：一股脑把能想到的能力全部封装成技能，结果技能之间互相覆盖、边界模糊，模型经常调度到错误的技能上。后来我调整了策略，从三个维度重新组织整个体系：技能怎么分类、技能怎么定义、技能怎么被调度。

2.1 技能分类：原子技能、组合技能、策略技能

从日常复用角度看，技能可以分成三类。理解这三类的差别，是设计技能体系的基础。

原子技能是“不可再拆分的最小执行单元”。比如“调用地图接口计算两点距离”“解析某格式的文档”“发送一条 HTTP 请求”，这些动作本身不依赖其他技能，输入输出都很清晰。设计原子技能时，目标就是让它们像乐高基础积木一样，单个朴实，但可靠耐用。

组合技能是把若干原子技能按固定顺序编排成一个完整流程。比如“生成周报”，内部顺序可能是“拉取项目数据、分析数据变化、归纳重点事项、生成 Markdown 文本、发送到指定渠道”，每一步调用一个原子技能或简单工具，组合技能就是那条固定的流水线。组合技能适合业务逻辑相对固定的高频场景。

策略技能是给模型更多自由裁量权的复杂流程，内部可能包含多个分支和判断条件，模型需要根据实际情况动态选择要走哪条路。比如“竞品分析”，模型可能先决定调用搜索技能获取信息、再调用网页正文提取技能、再调用总结技能，中途发现信息不够，还会追加一次搜索。策略技能是技能体系里最有弹性的部分，也是模型能力发挥最明显的部分。

2.2 技能的输入输出协议：一切都要可预期

技能封装的本质是把“不确定性”关在门外，这要求每个技能必须有严格的输入输出协议。我在实际项目里，给每个技能定义了以下字段：

• 技能名称（name）：机器可读的唯一标识，比如fetch_webpage_content
• 技能描述（description）：一段话说明这个技能做什么、什么时候用、什么时候不要用。这段话极其关键，因为模型是靠它来调度技能的
• 输入参数（parameters）：一个 JSON Schema 对象，定义参数名、类型、是否必填、约束条件
• 返回格式（returns）：固定为 JSON，至少包含status、data、error三个字段
• 超时和失败处理（timeout & fallback）：超过多少毫秒应该终止，失败后返回什么信息，是否允许重试

很多初学者会忽略“输出协议”的重要性。举个例子，我之前写过一个技能，返回的是自然语言描述：“结果看起来不错，数据大约是 12345。”另一个技能需要用到这个数据时，还得额外写个解析函数去里面抓数字，非常容易出错。正确做法是返回{"status": "success", "data": {"total_count": 12345}}，让下游无论是代码还是模型都能直接消费。

2.3 调度机制：模型判断还是代码路由

说到调度，这里有一个原则问题：什么情况下让模型决定调用哪个技能，什么情况下由代码直接路由？

我的做法是：主流程的稳定性靠代码，弹性靠模型。像“用户发起请求 -> 判断意图 -> 选择合适的技能组合”这一步，大部分场景我会用代码先做一次意图路由。比如用户说“帮我查下昨天的订单量”，代码可能直接匹配到“数据查询技能”；但如果查询条件不明确，代码再把控制权交给模型，让模型通过对话澄清参数，或者自主决定生成查询计划。

这样做的好处很直观：降低模型被无关技能干扰的概率。如果所有请求都直接丢给模型去几十个技能里挑选，不仅推理成本高，而且经常会因为描述相近而选错。代码先把范围缩小到 3-5 个候选技能，模型再从中选择，准确率会高很多。

3. 实操：从零搭建一个可落地的技能包

前面讲了不少设计层面的东西，有人可能会觉得“这不就是把函数封装了一下吗”。但区别恰恰在实操细节上。这里我以“信息收集与要点提取”为例，完整演示一个技能包从定义到实现的全过程。

3.1 环境准备与基础依赖

我现在的项目环境是 Python 3.11，使用 FastAPI 作为技能服务的 HTTP 框架，用 pydantic 做输入输出校验，技能仓库则放在一个独立的目录结构里。这个组合在团队协作、单元测试、接口对接上都很成熟。

技能的目录结构大概是这样：

skill_repo/ ├── registry.py # 技能注册中心，负责加载所有技能包 ├── schema.py # 输入输出定义的通用基类 ├── skills/ │ ├── fetch_web/ # 一个技能包 │ │ ├── __init__.py │ │ ├── skill.py # 技能核心逻辑 │ │ └── tests/ # 单元测试 │ ├── parse_doc/ # 另一个技能包 │ │ ├── __init__.py │ │ └── skill.py │ └── ... └── router.py # 技能路由与调度逻辑

每个技能包的注册，本质上是声名了一个带有“名称、描述、参数 schema、处理函数”的对象。注册中心启动时扫描所有技能包，把它们转换成统一的技能描述列表，后续无论是供模型选择的“可用技能列表”，还是供代码路由使用的“路由表”，都从这个注册中心读取。

3.2 定义一个可复用的技能：公共协议参考

先看技能的输入输出定义部分。下面是一个参考性质的定义，我用来管理同类型技能的共性要求，实际字段需要根据自己的业务去扩展：

from pydantic import BaseModel, Field from typing import Optional class SkillInput(BaseModel): query: str = Field(description="用户查询的主要内容") language: str = Field(default="zh", description="返回内容的语言") max_chars: int = Field(default=2000, ge=100, le=10000, description="返回内容的最大长度") class SkillOutput(BaseModel): status: str = Field(description="执行状态：success / error / timeout") data: Optional[str] = Field(default=None, description="成功时返回的内容") error: Optional[str] = Field(default=None, description="失败时的错误信息")

这个定义的核心作用，是让技能在入口和出口上都标准化。入口参数不管来自用户、上游代码还是模型生成，都必须经过 pydantic 校验；出口结果不管内部逻辑多复杂，最终都收敛到一个统一的 JSON 结构里。这一步能避免你在下游做无数种兼容处理。

3.3 技能核心逻辑实现与注意点

接下来是技能的核心实现。以“提取网页核心要点”为例，我封装了这样三层逻辑：

第一层是安全校验。很多团队会把“是否能访问某个域名”这类权限校验放在技能内部。收到 URL 之后，第一步校验协议是否允许访问目标域名或 IP，避免内网地址段被探测到。这一步其实很重要，很多安全事故都始于一个不加限制的“抓取网页”技能。

第二层是抓取与解析。使用成熟的 HTML 解析器抽取正文内容，去除脚本、样式、导航等无关元素。这里有一个技术细节：不同网站的正文结构差异极大，单纯依赖某一种抽取规则效果很差。我的做法是先用主流的正文抽取算法处理，同时对结果做一次“正文密度评分”；如果评分偏低，再切换到通用内容提取方案，用样式标签和文本块分布来定位正文区域。

第三层是后处理。把抽取到的原始文本做清洗，去除多余空行、乱码字符，再截断到指定长度。这个过程还需要保留关键结构的完整性，比如不要因为截断而把一句完整的话从中间切断，否则后续做摘要或问答时，信息完整性会受损。

def run_skill(input_data: SkillInput, context: dict) -> SkillOutput: url = input_data.query.strip() # 第一层：安全校验 check_result = validate_target_url(url, context) if not check_result.allowed: return SkillOutput(status="error", error="target not allowed") # 第二层：抓取与正文提取 html_content = fetch_html(url, timeout=context.get("request_timeout", 10)) main_text = extract_main_content(html_content) if len(main_text) < 50: return SkillOutput(status="error", error="content too short to extract") # 第三层：清洗与截断 cleaned_text = clean_text(main_text) trimmed_text = ensure_whole_sentence(cleaned_text, max_chars=input_data.max_chars) return SkillOutput(status="success", data=trimmed_text)

这里再强调一个实际经验：如果正文清洗后长度非常短，大概率是目标页面内容本身是动态渲染的（需要通过浏览器执行脚本才能拿到），或者是一个需要登录后才能看到全文的页面。这时候，单纯靠技能内部的抓取逻辑解决不了问题，比较好的方式是让技能返回一个明确的错误状态，由上层策略提示用户“该页面无法直接解析”，而不是让模型自己脑补一个内容出来。我见过很多 Agent 在拿不到页面内容时强行编排一个看似合理的回答，这是非常危险的幻觉来源。

3.4 注册技能并完成最小调度测试

技能逻辑写完，只是完成了一半。想让 Agent 能用起来，还差注册和调度测试两步。

注册这一步，本质是把技能的信息送入注册中心。注册中心启动时会扫描所有技能包，拿到每个技能的“名称、描述、参数、执行函数”，然后生成两个东西：一个给模型看的技能描述列表，一个给代码路由用的函数映射表。

# registry.py 的核心抽象 skill_registry = {} def register_skill(name, description, parameters_schema, handler): skill_registry[name] = { "name": name, "description": description, "parameters_schema": parameters_schema, "handler": handler, } def list_skills_for_model(): return [ {"name": s["name"], "description": s["description"], "parameters": s["parameters_schema"]} for s in skill_registry.values() ]

注册完成后，推荐先做一轮最小调度测试。我会模拟一个用户输入，让模型输出“需要调用哪个技能以及参数是什么”，然后代码接管执行，最后把结果回传给模型。这里的关键测试点是：模型能不能在参数缺失时主动询问，而不是自作主张填一个默认值。如果模型经常填错参数，说明技能描述和参数 schema 写得不够清晰，需要回头优化描述语言，而不是责备模型。

4. 技能管理、团队协作与持续迭代

技能体系不是一次性建完就万事大吉的。业务会变、模型能力会变、工具接口会变，技能仓库必须像代码仓库一样持续维护。这个章节分享我在技能管理、路由和团队协作上的一些做法。

4.1 技能仓库的命名规范与版本管理

技能仓库里最影响维护体验的就是命名规范。我踩过的坑是：一开始技能名起得随意，同一个功能有parse_web、web_to_text、get_web_content等好几个名字，导致模型调度时经常混淆。后来我统一了命名规则，遵循“动作_对象_场景”的结构：

• fetch_webpage_content：获取网页正文
• parse_pdf_to_text：解析 PDF 内容
• query_order_statistic：查询订单统计
• calc_coupon_final_price：计算券后价

这个规则保证工程师看到名字就能大概知道功能，模型也能从名称中提取更多语义信息。版本管理方面，我建议给每个技能包维护独立的版本号，与技能仓库整体版本解耦。这样当某个技能因为业务需求改动而影响整体时，可以在技能描述里加上历史版本备注，方便回滚和对比。

4.2 多技能协作：如何避免模型“选错技能”

多技能协作中最常遇到的问题就是选错技能。选错的原因，通常不是模型笨，而是技能描述写得模糊，技能边界互相覆盖。比如“查询订单”和“查询订单详情”，名字只差两个字，描述也都提到“获取订单信息”，模型自然容易混淆。

解决的方法有三个。第一个是边界声明，在技能描述里明确强调“什么时候用我、什么时候别用我”。例如：

查询订单列表，根据用户提供的筛选条件返回订单摘要。当且仅当用户需要查看多条订单的汇总信息时使用；如果用户明确询问某一笔订单的物流状态，请优先调用“查询订单物流”技能。

第二是意图预分类。在代码层先用一个简单分类器或规则把请求分成“查询类、计算类、生成类、控制类”，再只把对应类别下的技能列表提供给模型，缩小选择范围。第三是引入反馈和修正。当发现模型连续若干次在某一对技能之间选错，不一定是继续调提示词，而是检查是不是应该把这两个技能合并成一个更高级的组合技能，或者在代码层直接加路由规则。

4.3 技能的可观测性：每一次调用都要可追溯

在真实业务里，Agent 出错不可怕，可怕的是出错之后不知道怎么排查。所以我建议：每个技能在执行时都要吐出一份“执行轨迹”。我通常在技能返回结果里额外附带一段调试信息，包括入参、实际执行的 URL、返回的字节数、耗时、异常类型等。这些信息平时不进最终展示给用户的内容，但如果线上出问题，工程师可以拿着这次请求的会话 ID，把整条技能调用链完整还原出来。

这样做还有一个额外好处：可以在开发阶段用这些轨迹做回归测试。积累一批标注后的历史问题样本，等技能代码更新后，拿这批样本重新跑一遍，就能快速发现哪些技能的行为发生了非预期变化。

5. 常见坑与排查心得

最后这部分分享几个我在实际项目中反复遇到的典型问题，以及对应的排查思路和解决办法。这些坑基本文档里不会写，但遇到一个就能费你半天时间。

5.1 技能描述写得太“文艺”

我见过有团队把技能描述写成：“此技能用于优雅地获取网页中的精髓内容。”描述里充满了“精准”“高效”“智能”这类修饰词。结果就是模型根本搞不清楚它到底处理什么格式、适合什么场景、不适合什么场景。技能描述应该像给机器人写操作手册，而不是写作文。

建议写法直接一些：“输入一个 URL，返回该网页正文的纯文本内容，适用于新闻文章、博客、技术文档等静态页面；不适用于需要登录、嵌入在图片中的内容或由 JavaScript 动态加载的页面。”

5.2 工具链过长导致错误雪崩

组合技能里如果编排了 7-8 个步骤，任何一个步骤出错，后面全部跟着失败，而且错误信息一层层叠加，最后模型拿到一堆混在一起的报错文本，几乎不可能正确判断该如何兜底。我的经验是：组合技能要设置“止损点”。

所谓止损点，就是在编排流程时定义清楚：哪些步骤失败是可以重试的、哪些步骤失败应该直接终止并返回部分结果、哪些步骤失败需要切换到备选方案。比如“生成周报”这个组合技能，如果“拉取项目数据”失败，就不应该继续执行“生成 Markdown”，而应该直接终止，并返回“数据获取失败，已终止流程”。把失败模式在代码层定义清楚，而不是留给模型临场判断，整个流程的稳定性会高很多。

5.3 ignore context 导致的上下文污染

当 Agent 的技能变多之后，另一个高频问题就是上下文污染。技能 A 返回了一大段中间结果，然后技能 B 执行时“看到”了这段结果，可能错误地把它当作自己需要的输入。更麻烦的是，有些模型在上下文里看到完整返回内容后，会直接复制粘贴其中的数字或者结论，跳过自己的推理过程。

应对策略是强制执行“上下文隔离”。我在技能调度层加了一个约束：仅当某个技能的返回值被显式声明为“可传递”时，它才会以完整内容的形式暴露给下一次模型调用；否则，技能内部的过程性输出只走日志记录，不进入对话上下文。这样做可能会损失一点信息通路上的灵活性，但换来的是大幅减少随机性错误，很值得。

5.4 测试覆盖不全：技能只在“理想路径”上被验证

大多数团队测试技能时，只测“正常输入下返回正常结果”。真实业务里，错误输入、边界情况、网络抖动导致的超时，往往占了一半以上的调用流量。我一直建议，每个技能包都应该附带一组异常测试用例，至少覆盖这几种情况：

• 输入参数缺入或类型错误，是否返回标准错误结构
• 目标资源不可达（超时、404、内容为空），是否返回可理解的错误信息
• 返回内容超长，是否按约定截断且不破坏文本结构
• 多次连续调用时，是否出现状态残留（静态变量污染）

我甚至会在 CI 流程里挂一个“随机故障注入”的测试任务，人为让某个依赖接口有概率返回 500 或延迟，看整个组合技能能不能正确地走到兜底分支。这个习惯确实帮我提前发现过很多问题。

5.5 技能权限过大：安全边界要前置

最后一个坑，也是我认为最容易引起重大事故的坑：技能权限过大。比如一个“发送邮件”技能，如果参数没有限制收件人范围，一旦模型被诱导发出了错误指令，可能把不该发的内容发给不该发的人。再比如“查询数据”技能，如果允许传入任意 SQL，那模型生成的查询条件就可能导致敏感数据被拉取。

我的建议是：技能在入口处做严格的“授权校验”，权限收得尽可能小。比如发送邮件，技能内部只允许向白名单内的收件人发送，并且所有外发内容都需要经过定义好的审核流；查询数据则使用预编译的查询模板，不允许模型直接拼接任意结构化查询。这些前置约束会让 Agent 看起来“没那么灵活”——但说实话，在真实业务里，安全边界比灵活重要得多。你永远不希望在事故之后才意识到，当初为了省事把整个数据库访问权限开放给了模型。

6. 后续可以做的一些扩展方向

技能体系搭建完成并稳定运行一段时间后，你会发现它的价值远不止“当前这些技能”，更在于它能支撑更复杂的自动化任务。我这里简单说几个我认为值得投入的方向，供你参考。

第一个方向是技能自动生成。既然一个技能本质上是“描述 + 参数 Schema + 处理函数”，那是否可以由 Agent 根据业务需求自动生成新技能？我在实验中发现，让模型写一个函数不难，难的是自动产出高质量的描述和参数校验规则。但如果把生成范围限制在一些模式固定的场景（比如“为某个 API 生成一个查询技能”），效果已经相当可用了。

第二个方向是跨场景技能迁移。一个团队沉淀的技能体系，如果描述、命名、协议都规范，理论上可以迁移到另一个业务线复用。比如在某个团队里已经封装好的“网页正文提取”技能，到了另一个团队做舆情分析时，依然可以原样加载使用。这有点像一个内部的“技能插件市场”，跨项目复用可以节省大量重复开发成本。

第三个方向是技能执行效果评估。很多团队知道要评估模型输出，但很少评估“技能执行路径是否合理”。我最近在做的一件事是：让一个独立的评估模型仅仅基于“用户输入”和“技能调用轨迹”，判断这个轨迹是否绕了弯路、是否有更优的技能组合、是否出现了冗余调用。这些标注结果，可以反过来优化路由逻辑和技能描述。

如果你已经走到了这一步，说明你的 Agent 不只是“能聊天”，而是真的在往“能干活”的方向进化了。把技能体系做扎实，本质上是在给 Agent 建一个有序、可控、可维护的“能力工具箱”——这比堆砌再多的模型参数都管用。以后你每新增一个业务场景，不再是重新调一轮提示词，而是看看现有技能库能不能直接组合覆盖它。这个转变，会给开发和维护效率带来实实在在的改善。