Agent-Skills工程化实践：构建可复用智能体技能体系

1. 从“agent-skills”这个标题说起：它到底在解决什么问题

第一次看到“agent-skills”这个标题，我脑子里蹦出来的不是某个具体框架，而是一类很实在的工程痛点：智能体（Agent）能跑起来不难，难的是让它稳定地把一件事做完、做对、做得可复用。过去一年多，我经手过好几个基于大模型的自动化项目，从客服工单分类到多步骤数据整理，踩过的坑几乎都指向同一个根源——大家把注意力全放在“模型选哪个”“提示词怎么写”上，却忽略了智能体真正干活靠的是一套可组合、可测试、可复用的能力单元，也就是标题里说的 skills。

所以这篇博文，我想把“agent-skills”当成一个工程化的能力体系来拆。它不是一个具体的开源库名字，而是一种设计思路：把智能体需要具备的每一项本领，拆成独立、边界清晰、输入输出明确的技能模块，再通过统一的调度层把它们串起来。这样做的直接好处是，模型换了、提示词改了，技能本身不用重写；某个环节出问题，能快速定位到具体是哪个 skill 挂了，而不是对着一个几百行的巨型提示词干瞪眼。

这篇文章适合谁看？如果你正在做智能体相关的开发，或者准备把大模型接入到实际业务流程里，又或者你已经被“提示词越写越长、效果越来越玄学”折磨过，那这篇内容应该能帮到你。我会从整体设计思路讲到具体实现，再到排查技巧，尽量把每一步背后的“为什么”说清楚，让你看完能直接照着搭一套自己的技能体系。全文基于我自己的实践和常见工程做法整理，涉及具体参数的地方我会给出计算或选择依据，方便你按自己的场景调整。

2. 整体设计思路：为什么要把智能体拆成技能

2.1 单体提示词的三个死穴

先说清楚为什么要拆。很多人做智能体的第一反应是写一个“万能提示词”，把角色设定、任务步骤、输出格式、异常处理全塞进去。我早期也这么干过，结果遇到三个绕不过去的问题。

第一个是上下文膨胀。一个稍微复杂点的任务，提示词轻松突破两三千字，再加上对话历史和工具返回结果，很快就逼近模型的上下文窗口上限。一旦超限，要么截断丢信息，要么被迫换更贵的模型，成本直接起飞。

第二个是调试困难。当智能体输出不对时，你很难判断是角色设定有问题、某一步骤描述不清，还是工具调用参数错了。整个提示词是一个黑盒，改一处可能影响另一处，回归测试基本靠人肉。

第三个是复用性差。你在A项目里写好的“日期解析”逻辑，到了B项目想用，只能复制粘贴，然后随着两边需求分化，慢慢变成两份互相不知道对方存在的代码。这种技术债积累起来非常可怕。

2.2 技能化拆分的核心逻辑

“agent-skills”的思路，本质上是把软件工程里“高内聚、低耦合”的原则搬到智能体设计上。每个 skill 是一个独立单元，它至少包含四样东西：明确的职责描述、规范的输入结构、可预期的输出结构、以及失败时的处理策略。

打个生活化的比方。单体提示词就像让一个全能管家同时负责做饭、洗衣、记账、接送孩子，你只告诉他“把家里打理好”。而技能化拆分，是你雇了一个调度员，他手里有一份清单：做饭找厨师、洗衣找保洁、记账找会计。调度员只负责判断“现在该找谁”，具体怎么炒菜、怎么分类衣物，是各个专业角色自己的事。这样一来，换厨师不影响保洁，加一项“遛狗”也只需要新增一个角色。

从工程角度看，这种拆分带来三个直接收益。可测试性：每个 skill 可以单独写测试用例，输入固定数据看输出是否符合预期。可观测性：调度层可以记录每个 skill 的调用耗时、成功率、失败原因，形成完整的链路追踪。可演进性：某个 skill 要升级，只要保持输入输出契约不变，上层调度完全无感。

2.3 技能体系的四层结构

基于我的实践，一套完整的 agent-skills 体系通常分四层，从下往上依次是：

这个分层不是强制标准，但它的好处是每一层只依赖下一层，不会出现跨层乱调。我见过一些项目把检索逻辑直接写进调度层，结果调度层越来越臃肿，最后又变回单体提示词。分层清晰，后续扩展才不会失控。

注意：分层不是越多越好。小项目两三层就够，硬套四层反而增加维护成本。判断标准很简单——如果某一层只有一个技能，且短期内不会增加，那它就没必要独立成层。

3. 核心细节解析：一个 skill 到底该怎么定义

3.1 技能描述的三要素

定义一个 skill，我习惯用三要素来约束：触发条件、执行逻辑、输出契约。这三样缺一不可，缺了任何一个，调度层就没法可靠地使用它。

触发条件回答“什么时候该用这个技能”。它可以是关键词匹配，也可以是语义相似度判断，还可以是上游调度层的显式指定。我倾向于把触发条件写得具体一些，比如“当用户输入包含日期范围且需要按时间聚合时”，而不是笼统的“处理时间相关任务”。条件越具体，误触发的概率越低。

执行逻辑是技能的主体。这里有个关键原则：技能内部不应该再做意图判断。也就是说，一个负责“解析日期字符串”的技能，就只管解析，不要在里面判断“用户是不是想查天气”。意图判断是调度层的事，技能只做被明确要求做的事。这条原则能极大降低技能之间的耦合。

输出契约规定技能返回什么。我强烈建议所有技能都返回结构化的数据，而不是一段自然语言。比如日期解析技能返回{"start": "2024-01-01", "end": "2024-01-31", "granularity": "month"}，而不是“我解析出开始时间是……”。结构化输出让下游处理更稳定，也方便写自动化测试。

3.2 输入输出的结构化设计

说到结构化，这里展开讲一下输入输出的设计细节，因为这是最容易埋坑的地方。

输入方面，我建议每个技能都接收一个统一的上下文对象，里面包含原始用户输入、上游传递的参数、以及必要的环境信息。这样做的好处是技能之间传递数据有统一格式，新增字段不会破坏已有技能。一个典型的输入结构长这样：

{ "raw_input": "帮我整理一下上个月的销售数据", "params": { "time_range": "last_month", "data_source": "sales_db" }, "context": { "user_id": "u_1001", "session_id": "s_20240115_001", "previous_skills": ["intent_recognize"] } }

输出方面，除了业务数据本身，我建议统一带上三个元字段：status（成功/失败/部分成功）、confidence（置信度，0到1之间）、error（失败时的错误信息）。这三个字段看起来简单，但在排查问题时价值巨大。比如某个技能返回confidence: 0.3，调度层就可以决定是否要触发澄清追问，而不是硬着头皮往下走。

3.3 技能粒度的把握

粒度是设计技能时最纠结的问题。拆得太细，技能数量爆炸，调度层要维护一张巨大的路由表；拆得太粗，又回到单体提示词的老路。

我的经验法则是：一个技能应该对应一个可以用一句话描述清楚、且不需要内部再做分支判断的操作。比如“从文本中提取所有邮箱地址”是一个合适的粒度；“处理用户关于账号的所有请求”就太粗了，因为里面必然包含查询、修改、重置等多个分支。

还有一个实用判断标准：如果一个技能内部出现了超过三个 if-else 分支，就该考虑拆分了。分支意味着不同的处理路径，不同路径往往可以独立成技能，由调度层来决定走哪条。

另外，粒度和复用性强相关。粒度越细，复用性越高，但组合成本也越高。实际项目中我会先按粗粒度实现，等发现某个子操作被反复调用时，再把它抽出来独立成技能。这种“按需拆分”的策略比一开始就追求完美粒度要务实得多。

4. 实操过程：从零搭一套技能体系

4.1 环境准备与目录结构

动手之前先把工程结构定好，后面会省很多事。我用的是 Python 技术栈，核心依赖就几个：一个大模型调用库、一个数据校验库（推荐 pydantic）、一个测试框架。目录结构大致如下：

agent_skills/ ├── skills/ # 所有技能实现 │ ├── base.py # 技能基类 │ ├── date_parser.py │ ├── text_extractor.py │ └── data_aggregator.py ├── dispatcher/ # 调度层 │ ├── router.py │ └── intent.py ├── schemas/ # 输入输出结构定义 │ └── common.py ├── tests/ # 测试用例 └── config/ └── skills.yaml # 技能注册配置

这个结构的关键点是技能实现和调度逻辑物理隔离。skills/目录下的代码不应该 importdispatcher/里的任何东西，依赖方向是单向的。这样你才能单独测试每个技能，也才能在别的项目里直接复制某个技能文件而不拖泥带水。

4.2 技能基类的实现

所有技能继承同一个基类，基类负责统一处理输入校验、日志记录、异常捕获这些横切关注点。这样每个具体技能只需要专注业务逻辑。核心代码大概是这样：

from abc import ABC, abstractmethod from pydantic import BaseModel class SkillInput(BaseModel): raw_input: str params: dict = {} context: dict = {} class SkillOutput(BaseModel): status: str confidence: float data: dict = {} error: str = "" class BaseSkill(ABC): name: str = "" description: str = "" @abstractmethod def execute(self, input_data: SkillInput) -> SkillOutput: pass def run(self, input_data: SkillInput) -> SkillOutput: try: validated = SkillInput(**input_data.dict()) result = self.execute(validated) self._log(input_data, result) return result except Exception as e: return SkillOutput( status="failed", confidence=0.0, error=str(e) )

这里有几个设计决策值得说明。为什么用 pydantic 做输入校验：因为技能之间传递的数据格式容易出错，pydantic 能在入口就把格式问题拦下来，报错信息也清晰。为什么把异常捕获放在基类：技能内部抛异常是正常的，但调度层不应该被异常打断，统一在基类兜底能让整个链路更健壮。为什么 confidence 默认给 0：失败时置信度必须是 0，避免下游误用。

4.3 一个具体技能的完整实现

拿“日期范围解析”这个技能举例，它接收自然语言里的时间描述，输出结构化的起止日期。这个技能在实际项目里复用率极高，几乎每个涉及数据查询的智能体都会用到。

from datetime import datetime, timedelta import re class DateParserSkill(BaseSkill): name = "date_parser" description = "将自然语言时间描述解析为结构化日期范围" def execute(self, input_data: SkillInput) -> SkillOutput: text = input_data.raw_input today = datetime.now().date() if "上个月" in text: first_this_month = today.replace(day=1) last_month_end = first_this_month - timedelta(days=1) last_month_start = last_month_end.replace(day=1) return SkillOutput( status="success", confidence=0.95, data={ "start": str(last_month_start), "end": str(last_month_end), "granularity": "month" } ) match = re.search(r"(\d{4})年(\d{1,2})月", text) if match: year, month = int(match.group(1)), int(match.group(2)) start = datetime(year, month, 1).date() if month == 12: end = datetime(year + 1, 1, 1).date() - timedelta(days=1) else: end = datetime(year, month + 1, 1).date() - timedelta(days=1) return SkillOutput( status="success", confidence=0.9, data={"start": str(start), "end": str(end), "granularity": "month"} ) return SkillOutput( status="failed", confidence=0.0, error="无法识别的时间描述" )

这段代码里，置信度的赋值是有讲究的。“上个月”这种相对时间，因为依赖当前日期，我给了 0.95；而“2024年3月”这种绝对时间，解析逻辑更确定，理论上可以给更高，但考虑到正则可能匹配到非预期文本，我给 0.9。这些数值不是拍脑袋，而是根据实际测试中各类输入的准确率统计出来的。你可以在自己的项目里先给个初值，跑一批测试用例后按实际准确率调整。

4.4 调度层的路由逻辑

技能写好了，接下来是调度层怎么决定用哪个。最简单的做法是关键词匹配，但这种方式在输入表达多样时很容易漏。我的做法是关键词匹配 + 语义相似度兜底两级路由。

第一级用关键词快速筛选，命中就直接调用，这是为了性能和确定性。第二级用向量相似度，把用户输入和每个技能的 description 做 embedding 比对，取相似度最高的那个，但设一个阈值（我一般用 0.75），低于阈值就返回“无法确定意图”，触发澄清追问。

def route(self, user_input: str) -> str: # 第一级：关键词匹配 for skill_name, keywords in self.keyword_map.items(): if any(kw in user_input for kw in keywords): return skill_name # 第二级：语义相似度 input_vec = self.embed(user_input) best_skill, best_score = None, 0.0 for skill in self.skills: skill_vec = self.embed(skill.description) score = cosine_similarity(input_vec, skill_vec) if score > best_score: best_skill, best_score = skill.name, score if best_score < 0.75: return "clarify" return best_skill

阈值 0.75 这个数是我在几个项目里试出来的经验值。设太高（比如 0.85），很多合理请求会被判为“无法确定”，用户体验差；设太低（比如 0.6），又容易把不相关的技能匹配上，导致答非所问。0.75 在我的测试集上准确率和召回率比较平衡，但你的场景不同，建议自己跑一批标注数据来定。

4.5 技能注册与配置化

技能不应该硬编码在调度层里，而是通过配置文件注册。这样新增技能只需要加一个文件、改一行配置，不用动调度代码。

skills: - name: date_parser module: skills.date_parser class: DateParserSkill keywords: ["上个月", "本月", "日期", "时间范围"] enabled: true - name: text_extractor module: skills.text_extractor class: TextExtractorSkill keywords: ["提取", "抽取", "找出"] enabled: true

配置化还有一个好处是可以按环境开关技能。比如测试环境只开部分技能，方便定位问题；生产环境全开。这种灵活性在排查线上问题时特别有用。

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

5.1 技能误触发怎么排查

误触发是最常见的问题，表现是用户问A，系统却调用了处理B的技能。排查思路分三步走。

第一步，看路由日志。如果调度层记录了每次路由的决策依据（命中了哪个关键词，或相似度分数是多少），问题一目了然。我强烈建议在路由层加详细日志，这是排查效率最高的投入。

第二步，检查关键词冲突。多个技能的关键词如果有重叠，先命中的会赢。比如“日期”这个词既可能出现在日期解析技能里，也可能出现在日程管理技能里。解决办法是给关键词加优先级，或者把容易冲突的词从关键词列表里拿掉，交给语义相似度判断。

第三步，调整相似度阈值。如果误触发来自语义路由，说明阈值偏低。可以针对容易混淆的技能对，单独提高它们之间的区分阈值。

5.2 技能返回结果不稳定

同一个技能，同样的输入，有时返回对有时返回错，这种问题最让人头疼。根据我的经验，原因通常有三个。

一是技能内部依赖了外部不确定因素，比如调用了大模型但没有固定随机种子，或者依赖了当前时间但没在测试时 mock。解决办法是把所有外部依赖显式化，该传参的传参，该 mock 的 mock。

二是输入数据本身有歧义。比如“整理一下数据”这种输入，技能内部如果做了猜测，不同时候猜的结果可能不同。正确的做法是技能遇到歧义输入时返回低置信度，由调度层决定是否追问，而不是自己硬猜。

三是并发或状态污染。如果技能内部用了全局变量或类变量存状态，多个请求并发时会互相干扰。技能应该设计成无状态的，所有状态通过输入输出传递。

5.3 常见问题速查表

5.4 几个踩过的坑

坑一：技能之间直接互相调用。我早期为了图方便，让技能A直接 import 技能B来复用逻辑。结果后来技能B改了接口，技能A莫名其妙挂了。正确做法是技能之间不直接调用，需要组合时由调度层编排，或者把公共逻辑抽到独立的工具模块里。

坑二：把提示词写死在技能代码里。提示词是需要频繁调整的，写死在代码里意味着每次改词都要重新部署。后来我把提示词抽到配置文件或数据库里，改词不用发版，效率高很多。

坑三：忽略技能的幂等性。有些技能涉及写操作（比如更新数据库），如果因为重试被调用两次，会产生重复数据。所有涉及副作用的技能都应该设计成幂等的，或者带上请求ID做去重。

坑四：测试用例只覆盖正常路径。我见过太多项目，技能测试只测了“输入正确时输出正确”，没测空输入、超长输入、特殊字符输入。结果上线后遇到边界情况直接崩。建议每个技能至少覆盖正常、空值、异常格式三类用例。

6. 技能体系的扩展与演进

6.1 从单技能到技能链

当业务变复杂，单个技能往往不够用，需要多个技能按顺序组合。比如“生成月度报告”这个任务，可能需要先调日期解析技能确定范围，再调数据查询技能拉数据，然后调聚合技能做统计，最后调格式化技能输出。这种技能链的编排，我建议用显式的流程定义，而不是让大模型自由发挥。

流程定义可以很简单，就是一个技能名列表加参数映射：

chains: monthly_report: steps: - skill: date_parser input: "${raw_input}" output_key: time_range - skill: data_query input: "${time_range}" output_key: raw_data - skill: data_aggregator input: "${raw_data}" output_key: summary

这种声明式编排的好处是流程可见、可测试、可回放。出问题时能清楚看到是哪一步挂了，而不是面对一个黑盒。

6.2 技能的性能优化

技能数量多了之后，性能会成为问题。主要的优化方向有三个。

缓存：对于输入相同、输出确定的技能（比如日期解析、格式转换），加一层缓存能大幅减少重复计算。缓存键用输入数据的哈希，注意要排除掉不影响结果的环境字段。

并行：如果技能链中有多个互不依赖的步骤，可以并行执行。比如同时查询多个数据源，最后合并结果。这需要调度层支持并行编排，实现上可以用异步任务。

懒加载：不是所有技能每次都要加载。按需加载技能模块，能减少启动时间和内存占用。特别是那些依赖重型库的技能，懒加载效果明显。

6.3 技能的可观测性建设

一套技能体系上线后，你需要知道它运行得怎么样。我建议至少采集这几类指标：每个技能的调用次数、成功率、平均耗时、置信度分布。这些指标能帮你发现很多问题。

比如某个技能成功率突然下降，可能是上游输入格式变了；某个技能耗时变长，可能是依赖的外部服务变慢；置信度分布整体左移，可能是 embedding 模型需要更新了。这些信号比等用户投诉要早得多。

日志方面，我建议记录每次调用的完整链路：谁调的、输入是什么、输出是什么、耗时多少。但要注意脱敏，用户敏感信息不能直接落日志。可以只记录数据的结构特征（字段名、类型、长度），不记录具体内容。

7. 我个人的一些实践体会

搭了几套技能体系之后，我最大的体会是：这套东西的价值不在于技术多先进，而在于它强迫你把问题想清楚。以前写单体提示词，很多边界情况是靠模型“猜”过去的，看起来能用，但心里没底。拆成技能之后，每个技能的输入输出都必须明确定义，那些模糊地带就藏不住了，要么补逻辑，要么明确报错。这个过程很痛苦，但做完之后系统的稳定性是质的提升。

另一个体会是不要过度设计。我见过有人一上来就设计十几层抽象，结果维护成本比收益还高。技能体系应该跟着业务需求长出来，而不是一开始就规划一个完美架构。先跑通最小闭环，遇到复用需求再抽象，遇到性能问题再优化，这种渐进式的方式更靠谱。

最后分享一个小技巧：给每个技能写一句“人话描述”。这句话不是给机器看的，是给团队里其他人看的。当新人接手时，他看代码可能一头雾水，但看这句描述就能快速理解这个技能是干嘛的。这句话也正好可以作为语义路由的 description 用，一举两得。描述要具体，比如“把‘上个月’‘2024年3月’这类时间说法转成起止日期”，而不是“处理时间”。越具体，路由越准，别人也越容易看懂。