从零搭建可复用Agent Skills体系：智能体技能模块化实践复盘

1. 从零搭建一个可复用的 Agent Skills 体系：我的完整实践复盘

最近半年我一直在折腾各种智能体项目，从最简单的对话机器人到能自主完成多步骤任务的复杂系统，踩过的坑比过去三年加起来都多。今天想聊的agent-skills这个主题，就是我在反复重构中沉淀下来的一套方法论——它不是什么高深框架，而是一套让智能体真正“能干活”的技能组织方式。简单说，agent-skills解决的核心问题是：如何把大模型的能力拆解成一个个可组合、可复用、可独立调试的技能单元，让智能体在面对复杂任务时不再是一团乱麻，而是像搭积木一样灵活调度。

这套东西适合谁看？如果你正在做智能体相关的开发，不管是刚入门想搞清楚“技能”到底该怎么设计，还是已经有一堆零散功能想系统化整理，又或者你只是好奇智能体背后的运作逻辑，这篇内容都能给你一些可以直接抄作业的思路。我会从整体设计、核心细节、实操过程到问题排查，把agent-skills这套体系掰开揉碎讲清楚，尽量说人话，少堆术语。

2. 为什么需要 Agent Skills：整体设计与思路拆解

2.1 从“万能提示词”到“技能模块化”的转变

刚开始做智能体的时候，我和大多数人一样，喜欢把所有指令塞进一个巨大的系统提示词里。比如要做一个能查资料、能写代码、能发邮件的助手，我就写一段几百行的提示词，告诉模型“你是XX助手，你可以做A、B、C、D……”。这种做法在任务简单时还能凑合，一旦任务复杂起来，问题就全暴露了：提示词越来越长，模型开始“遗忘”前面的指令；不同功能之间互相干扰，查资料的逻辑影响了写代码的输出格式；调试更是噩梦，改了一个地方，另一个地方莫名其妙就崩了。

后来我意识到，智能体的能力不应该是一锅炖，而应该像乐高积木一样，每个技能独立封装、独立测试、按需组合。这就是agent-skills的核心思路：把智能体的能力拆解成一个个独立的技能单元，每个技能有自己的触发条件、执行逻辑、输入输出规范，以及错误处理机制。这样做的好处非常明显——技能可以单独迭代，不会牵一发而动全身；技能可以复用，今天做的“网页摘要”技能，明天换个智能体照样能用；调试也变得简单，哪个技能出问题就查哪个，不用在几千行提示词里大海捞针。

2.2 技能拆分的粒度怎么把握

拆分粒度是设计agent-skills时第一个要面对的问题。拆得太粗，比如“处理用户请求”算一个技能，那跟不拆没区别；拆得太细，比如“提取文本中的第一个逗号”也算一个技能，那技能数量会爆炸，调度开销反而更大。我试过几种不同的粒度，最后总结出一个比较实用的判断标准：一个技能应该对应一个“原子化的业务动作”，这个动作有明确的输入和输出，且不需要依赖其他技能的内部状态。

举个例子，在一个内容处理智能体里，“从网页提取正文”是一个合适的技能粒度，因为它输入是URL，输出是纯文本，逻辑独立。“把正文翻译成中文”也是一个合适的技能，输入是文本，输出是译文。但“提取正文并翻译”就不适合作为一个技能，因为它其实是两个动作的组合，应该由调度层来编排。再比如“判断文本情感倾向”可以是一个技能，但“判断文本情感倾向并决定是否回复”就太粗了，因为“决定是否回复”涉及策略，应该放在调度层或者单独的策略技能里。

实际操作中，我习惯先用一个“技能清单”把智能体需要具备的能力全部列出来，然后逐个问自己：这个能力能不能用一句话说清楚输入和输出？如果能，就保留；如果不能，就继续拆。拆完之后再看有没有可以合并的，比如两个技能输入输出高度相似，只是参数不同，那就可以合并成一个带参数的技能。

2.3 技能之间的协作机制设计

技能拆好之后，下一个问题就是它们怎么协作。agent-skills体系里，技能之间不直接调用，而是通过一个调度层来协调。调度层负责解析用户请求，判断需要哪些技能，按什么顺序执行，以及如何处理技能返回的结果。这样做的好处是技能之间解耦，每个技能只需要关心自己的输入输出，不需要知道其他技能的存在。

调度层的设计有两种常见模式：一种是规则驱动，提前定义好“如果用户请求包含X，就调用技能A，然后调用技能B”；另一种是模型驱动，让大模型根据当前上下文动态决定调用哪个技能。我实际用下来，两种模式各有优劣。规则驱动稳定可控，但灵活性差，遇到没预设过的场景就抓瞎；模型驱动灵活，能处理复杂多变的请求，但有时候会“幻觉”出根本不存在的技能，或者调用顺序出错。我的做法是混合使用：核心流程用规则驱动保证稳定性，边缘场景用模型驱动兜底，同时给模型驱动的调度加上严格的技能白名单和参数校验，防止它乱来。

还有一个细节是技能的执行顺序。有些技能有依赖关系，比如必须先“提取正文”才能“翻译正文”，这种依赖需要在调度层显式声明。我一般会用一个有向无环图来描述技能依赖，调度层按照拓扑排序依次执行。如果某个技能执行失败，调度层需要决定是重试、跳过还是终止整个流程，这个策略也要提前配好。

3. 核心细节解析与实操要点

3.1 技能描述文件的结构设计

每个技能都需要一个描述文件，告诉调度层这个技能是干什么的、怎么调用、输入输出是什么格式。这个描述文件的结构设计直接影响到整个体系的可维护性。我经过多次迭代，最终固定下来一套包含以下字段的结构：

• 技能名称：唯一标识符，用英文小写加下划线，比如extract_article。
• 技能描述：一句话说明这个技能的功能，给调度层和模型看，要简洁准确。
• 触发条件：什么情况下应该调用这个技能，可以是关键词列表，也可以是一段自然语言描述。
• 输入参数：每个参数的名字、类型、是否必填、默认值、描述。
• 输出格式：技能返回的数据结构，最好用JSON Schema定义清楚。
• 执行逻辑：具体的实现代码或者对外部接口的调用方式。
• 错误处理：常见错误类型和对应的处理策略，比如超时重试、参数缺失提示等。
• 版本号：方便后续迭代和兼容性管理。

这套结构看起来有点繁琐，但实际用起来非常值。尤其是输入参数和输出格式的定义，能避免很多“技能之间传参对不上”的低级错误。我踩过的坑是早期没定义输出格式，结果一个技能返回字符串，另一个技能期望的是字典，调度层直接崩溃。后来强制所有技能都用JSON Schema定义输出，问题就少多了。

3.2 技能执行引擎的关键实现

技能执行引擎是agent-skills体系的心脏，它负责加载技能描述文件、解析调度指令、执行技能、处理异常。我用的是一种插件式架构：每个技能是一个独立的模块，执行引擎在启动时扫描技能目录，动态加载所有技能。这样做的好处是新增技能不需要改引擎代码，只要把技能文件放进目录就行。

执行引擎的核心流程大概是这样：首先接收调度层传来的技能调用请求，包含技能名称和输入参数；然后根据技能名称找到对应的技能模块，校验输入参数是否符合Schema；接着执行技能逻辑，这里要注意设置超时时间，防止某个技能卡死整个流程；执行完成后校验输出格式，如果不符合就触发错误处理；最后把结果返回给调度层。

这里有个容易被忽略的细节：技能执行时的上下文隔离。如果多个技能共享同一个全局状态，很容易出现互相干扰。我的做法是每个技能执行时都创建一个独立的上下文对象，技能只能读写自己的上下文，需要跨技能传递的数据通过调度层显式传递。这样虽然麻烦一点，但能避免很多诡异的bug。

3.3 技能注册与发现机制

当技能数量多起来之后，怎么让调度层知道有哪些技能可用就成了一个问题。我试过两种方案：一种是静态注册，在配置文件里手动列出所有技能；另一种是动态发现，执行引擎启动时自动扫描技能目录并注册。静态注册的好处是可控，不会加载到不需要的技能；动态发现的好处是方便，新增技能不用改配置。

我最后选择了动态发现为主、静态配置为辅的方案：执行引擎启动时自动扫描技能目录，但同时支持一个“禁用列表”，把某些技能排除掉。这样既保留了灵活性，又能应对特殊情况。另外，我还加了一个技能健康检查机制，定期检查每个技能是否可用，比如依赖的外部接口是否正常，如果某个技能不可用就暂时从可用列表中移除，避免调度层调用到坏掉的技能。

4. 实操过程与核心环节实现

4.1 环境准备与基础依赖安装

开始搭建agent-skills体系之前，需要先准备好基础环境。我用的技术栈是 Python 3.10 以上，主要依赖以下几个库：pydantic用来做数据校验和Schema定义，httpx用来发异步HTTP请求，jinja2用来做提示词模板渲染，loguru用来做日志记录。这些库都是成熟稳定的，安装起来没什么坑。

pip install pydantic httpx jinja2 loguru

如果你打算把技能执行引擎做成服务，还可以加上fastapi和uvicorn，这样可以通过HTTP接口来调用技能。不过初期建议先用本地脚本跑通流程，等体系稳定了再考虑服务化。

目录结构我习惯这样组织：根目录下建一个skills文件夹，每个技能一个子文件夹，里面放技能描述文件skill.yaml和实现代码main.py。再建一个engine文件夹放执行引擎的代码，一个scheduler文件夹放调度层的代码。这样结构清晰，找东西方便。

4.2 编写第一个技能：网页正文提取

拿“网页正文提取”这个技能来举例，完整走一遍从描述文件到实现代码的流程。先写skill.yaml：

name: extract_article description: 从给定URL提取网页正文内容 trigger: keywords: ["提取正文", "网页内容", "文章内容"] input: url: type: string required: true description: 目标网页的URL output: title: type: string description: 文章标题 content: type: string description: 文章正文 success: type: boolean description: 是否提取成功 error_handling: timeout: 10 retry: 2 version: 1.0.0

然后写实现代码main.py。这里我用httpx发请求，用简单的正则和启发式规则提取正文。实际项目中你可能需要用更专业的正文提取库，但原理是一样的。

import httpx import re from loguru import logger async def execute(url: str) -> dict: try: async with httpx.AsyncClient(timeout=10) as client: resp = await client.get(url, follow_redirects=True) resp.raise_for_status() html = resp.text title_match = re.search(r'<title>(.*?)</title>', html, re.IGNORECASE) title = title_match.group(1).strip() if title_match else "" # 简单粗暴地去掉script和style标签 cleaned = re.sub(r'<script.*?</script>', '', html, flags=re.DOTALL | re.IGNORECASE) cleaned = re.sub(r'<style.*?</style>', '', cleaned, flags=re.DOTALL | re.IGNORECASE) # 提取所有段落文本 paragraphs = re.findall(r'<p[^>]*>(.*?)</p>', cleaned, re.DOTALL | re.IGNORECASE) content = "\n".join([re.sub(r'<[^>]+>', '', p).strip() for p in paragraphs if p.strip()]) return {"title": title, "content": content, "success": True} except Exception as e: logger.error(f"extract_article failed: {e}") return {"title": "", "content": "", "success": False}

这个技能写好后，放到skills/extract_article/目录下，执行引擎启动时就能自动加载。你可以单独测试这个技能，传入一个URL看返回结果是否符合预期。单独测试通过后，再接入调度层。

4.3 调度层的实现与技能编排

调度层的核心任务是把用户请求翻译成技能调用序列。我实现了一个简单的调度器，支持规则匹配和模型决策两种模式。规则匹配部分用关键词触发，比如用户请求里包含“提取正文”，就调用extract_article技能。模型决策部分则把可用技能列表和用户请求一起发给大模型，让模型输出应该调用的技能名称和参数。

class Scheduler: def __init__(self, engine): self.engine = engine self.rules = [ {"keywords": ["提取正文", "网页内容"], "skill": "extract_article"}, {"keywords": ["翻译"], "skill": "translate_text"}, ] async def dispatch(self, user_request: str) -> dict: # 先尝试规则匹配 for rule in self.rules: if any(kw in user_request for kw in rule["keywords"]): skill_name = rule["skill"] # 这里简化处理，实际需要从请求中提取参数 params = self._extract_params(user_request, skill_name) return await self.engine.execute(skill_name, params) # 规则没匹配到，走模型决策 return await self._model_dispatch(user_request)

调度层还需要处理技能之间的依赖。比如用户说“把这篇网页翻译成中文”，那就需要先调用extract_article，把返回的content作为translate_text的输入。我一般会在调度层里定义一个简单的依赖图，用拓扑排序确定执行顺序。如果某个技能执行失败，根据错误处理策略决定是重试还是终止。

4.4 技能组合与流程编排实战

实际场景中，用户请求往往需要多个技能组合完成。比如“帮我总结这篇网页的核心观点”，就需要extract_article提取正文，然后summarize_text做摘要。我在调度层里实现了一个简单的流程编排器，支持串行、并行和条件分支。

串行编排最简单，按顺序执行技能，前一个的输出作为后一个的输入。并行编排适合没有依赖关系的技能，比如同时提取正文和提取元数据。条件分支则根据某个技能的返回结果决定下一步走哪条路，比如提取正文失败就跳过摘要直接返回错误。

async def execute_pipeline(self, pipeline: list, initial_input: dict) -> dict: context = initial_input.copy() for step in pipeline: skill_name = step["skill"] params = {k: context.get(v) for k, v in step.get("param_map", {}).items()} result = await self.engine.execute(skill_name, params) if not result.get("success", True) and step.get("on_fail") == "abort": return {"success": False, "error": f"技能 {skill_name} 执行失败"} context.update(result) return context

这套编排机制虽然简单，但覆盖了大部分常见场景。我实际用下来，80%的需求用串行加条件分支就能搞定，剩下的20%才需要更复杂的编排逻辑。

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

5.1 技能加载失败与依赖缺失

技能加载失败是最常见的问题之一，表现是执行引擎启动时报错，或者调度层调用某个技能时提示“技能不存在”。排查思路一般是先看日志，确认是技能文件没找到、YAML格式错误，还是依赖库没安装。我踩过的坑是YAML文件里用了Tab缩进，导致解析失败，但报错信息很模糊，找了半天才发现。后来养成了习惯，所有YAML文件都用空格缩进，并且在加载时加一个格式校验步骤。

依赖缺失也很常见，尤其是技能实现里引用了某个库，但环境里没装。我的做法是在技能描述文件里加一个dependencies字段，列出这个技能需要的第三方库，执行引擎加载技能时先检查依赖是否满足，不满足就给出明确的提示，而不是等到执行时才报错。

5.2 技能执行超时与重试策略

技能执行超时通常是因为外部接口响应慢或者技能内部逻辑有死循环。我一般会给每个技能设置一个合理的超时时间，默认10秒，对于确实需要长时间执行的技能可以单独调大。超时后的处理策略要看场景：如果是查询类技能，可以重试；如果是写入类技能，重试要小心，避免重复写入。

重试策略我一般配置成指数退避，第一次失败等1秒重试，第二次等2秒，第三次等4秒，最多重试3次。如果3次都失败，就返回错误让调度层决定下一步。这里有个细节：重试时要确保技能是幂等的，否则可能产生副作用。对于不幂等的技能，我一般不做自动重试，而是返回错误让上层处理。

5.3 技能输出格式不匹配的排查

技能输出格式不匹配是另一个高频问题，表现是调度层拿到技能返回结果后解析失败，或者后续技能因为输入格式不对而报错。排查时先看技能实际返回了什么，跟描述文件里定义的Schema对比，找出差异。常见原因包括：技能实现里返回了额外的字段、字段类型不对（比如应该是字符串却返回了数字）、嵌套结构层级不对。

我的经验是在技能执行引擎里加一层输出校验，技能执行完成后自动用JSON Schema校验返回值，不符合就触发错误处理。这样问题能在技能层面暴露，而不是等到调度层才报错，排查起来容易得多。另外，技能实现里尽量用类型注解和Pydantic模型来构造返回值，能在编码阶段就发现类型问题。

5.4 调度层决策错误的调试方法

调度层决策错误的表现是调用了不该调用的技能，或者该调用多个技能时只调用了一个。如果是规则驱动模式，检查关键词列表是否覆盖了用户可能的表达方式，有时候用户换个说法就匹配不上了。如果是模型驱动模式，检查给模型的技能描述是否清晰，模型有时候会因为描述模糊而选错技能。

我一般会在调度层加详细的日志，记录每次决策的依据：匹配到了哪条规则、模型输出了什么、最终选择了哪个技能。这样出问题时能快速定位是规则问题还是模型问题。对于模型驱动模式，我还会加一个“决策置信度”字段，如果模型对某个技能选择的置信度低于阈值，就触发人工确认或者走兜底逻辑。

5.5 常见问题速查表

6. 技能体系的扩展与维护经验

6.1 技能版本管理与兼容性处理

技能多了之后，版本管理就成了必须面对的问题。我遇到过好几次因为技能升级导致调度层调用失败的情况，后来学乖了，给每个技能加版本号，调度层调用时指定版本，技能升级时保留旧版本一段时间，等所有调用方都迁移完成再下线旧版本。

版本号我用语义化版本规范，主版本号变更表示不兼容的接口改动，次版本号变更表示新增功能但向后兼容，修订号变更表示bug修复。技能描述文件里同时保留当前版本和历史版本的Schema定义，调度层根据调用时指定的版本加载对应的Schema做校验。这样即使技能升级了，旧调用方也不会突然崩掉。

6.2 技能性能监控与优化

技能执行性能直接影响整个智能体的响应速度。我一般会记录每个技能的执行耗时、成功率、错误类型分布，定期分析哪些技能是瓶颈。常见的性能问题包括：外部接口调用太慢、技能内部做了不必要的重复计算、技能之间数据传输量太大。

优化手段也对应着来：外部接口慢就加缓存或者换更快的接口；重复计算就加内存缓存；数据传输量大就只传必要字段，或者用引用代替完整数据。我实测下来，加一层简单的内存缓存就能把重复调用的技能耗时降低80%以上，效果非常明显。

6.3 技能复用与跨项目迁移

agent-skills体系最大的价值之一就是技能可以跨项目复用。我在一个项目里写的“网页正文提取”技能，换个项目直接复制过去就能用，不需要改任何代码。为了实现这一点，我在设计技能时就尽量让技能不依赖特定项目的配置，所有项目相关的参数都通过输入参数传入，而不是硬编码在技能实现里。

跨项目迁移时需要注意的是依赖库的版本兼容性。不同项目可能用不同版本的同一个库，如果技能实现里用了某个版本特有的API，迁移到另一个项目就可能报错。我的做法是尽量用稳定版本的库，并且在技能描述文件里明确声明依赖的版本范围，迁移时先检查目标项目的依赖版本是否满足。

6.4 技能文档与团队协作规范

当团队多人协作开发技能时，文档和规范就特别重要。我要求每个技能都必须有完整的描述文件，包括功能说明、输入输出示例、错误码定义。另外还定了一套命名规范：技能名称用英文小写加下划线，参数名用驼峰或者下划线保持一致，错误码用统一的前缀加数字。

代码审查时重点看几个方面：技能是否单一职责、输入输出是否校验、错误处理是否完善、是否有硬编码的项目相关配置。这套规范执行下来，团队里新人上手很快，技能质量也稳定得多。我个人的体会是，前期在规范上多花一小时，后期能省十小时的调试时间。

6.5 技能体系的持续迭代思路

agent-skills体系不是一次设计好就固定不变的，需要随着业务发展持续迭代。我一般每季度做一次技能盘点，看看哪些技能使用频率高、哪些几乎没人用、哪些经常出问题。高频技能重点优化性能和稳定性，低频技能考虑合并或下线，问题多的技能重点重构。

另外还会关注新的技能需求，比如业务方提出了新的场景，就需要评估是新增技能还是扩展现有技能。新增技能的成本包括开发、测试、文档、维护，如果现有技能稍作扩展就能覆盖，那优先扩展而不是新增。这个判断没有绝对标准，我的经验是如果新需求和现有技能的输入输出差异超过30%，就考虑新增技能，否则扩展。

7. 我在实际项目中的几点体会

这套agent-skills体系我从去年开始用，前后迭代了五六个版本，现在跑在生产环境里的技能有三十多个，覆盖了内容处理、数据分析、自动化操作等场景。最大的感受是技能拆分要克制，一开始我恨不得把每个动作都拆成技能，结果技能数量膨胀到上百个，调度层复杂得没法维护。后来狠心合并了一大批，把粒度控制在“一个业务动作”这个级别，整个体系才清爽起来。

另一个体会是错误处理要前置，不要等到技能执行时才考虑出错怎么办。我在技能描述文件里就把各种错误场景和应对策略定义好，执行引擎按策略自动处理，调度层只需要关心最终结果。这样虽然前期设计麻烦一点，但运行起来省心很多，不会因为某个技能报错就整个流程崩掉。

最后分享一个小技巧：给技能加一个“干跑”模式，也就是不实际执行技能逻辑，只校验输入参数和模拟输出。这个模式在调试调度层时特别有用，可以快速验证技能编排逻辑是否正确，而不用真的去调外部接口。等编排逻辑确认没问题了，再关掉干跑模式实际执行。这个功能帮我省了大量调试时间，强烈推荐你也加上。