agent-skills：从会聊到会做，智能体技能体系设计与实战

1. 从“会聊”到“会做”agent-skills 到底在解决什么问题大模型能写诗、能编故事、能陪你聊哲学但真让它帮你把一份 Excel 里的数据清洗完再生成图表它往往就卡壳了。这不是模型不够聪明而是它缺了“手”和“脚”——缺了把语言能力转化为实际行动的那套技能体系。agent-skills这个项目本质上就是在给智能体装上一套可插拔、可组合、可复用的能力模块让它从“只会说”进化到“能动手”。我最早接触这个概念是在做一个自动化报表工具的时候。当时用纯提示词让模型输出一段 Python 代码来合并多个 CSV 文件结果它每次生成的代码风格都不一样有的用 pandas有的用 csv 模块有的甚至直接手写循环读文件。更麻烦的是一旦文件路径里有中文或者空格生成的代码就各种报错。那时候我就意识到光靠提示词约束是不够的得把“读文件”“写文件”“执行命令”这些动作封装成标准化的技能让智能体像调用函数一样去调用它们而不是每次现编代码。agent-skills的核心思路就是技能即模块。每个技能是一个独立的功能单元有明确的输入输出定义、有边界条件说明、有错误处理逻辑。智能体在规划任务时先判断需要哪些技能再按顺序调用最后把结果整合起来。这套机制解决的是三个层面的问题第一稳定性——同样的任务每次执行结果一致不会因为模型随机性而时好时坏第二可维护性——某个技能出问题只需要修那一个模块不用重新调整个提示词第三可扩展性——新增能力只需要注册一个新技能不用改动智能体的核心逻辑。适合谁来参考这套东西如果你正在做智能体应用开发不管是客服机器人、数据分析助手还是自动化工作流工具只要涉及“让模型执行具体操作”这套技能体系都能直接套用。哪怕你只是用现成的智能体平台做自动化理解技能的设计思路也能帮你更好地编排任务流程。下面我会从设计思路、核心细节、实操过程、问题排查四个维度把agent-skills这套东西拆开揉碎讲清楚。2. 技能体系的设计哲学与架构选型2.1 为什么不是“一个大提示词走天下”很多人刚开始做智能体的时候习惯把所有指令塞进一个系统提示词里你是一个助手你可以读文件、写文件、发邮件、查数据库……然后指望模型自己判断什么时候该做什么。这种做法在任务简单、技能少的时候勉强能用一旦技能超过五六个模型就开始犯迷糊——该调用 A 的时候调了 B该传三个参数的时候只传了两个该先验证再执行的时候直接跳过了验证。我做过一个对比实验同样一个“从邮件附件提取表格并汇总”的任务用单提示词方案十次执行有三次失败失败原因包括附件路径解析错误、汇总逻辑写反、忘记关闭文件句柄。换成技能模块化方案后十次全部成功因为每个环节都被约束死了——读附件有专门的技能负责路径解析和格式校验汇总有专门的技能负责列匹配和计算写结果有专门的技能负责文件创建和权限检查。agent-skills的设计哲学可以概括为三条单一职责、显式契约、可组合性。单一职责是说一个技能只做一件事比如“读取 CSV 文件”和“解析 CSV 内容”应该是两个技能而不是一个“处理 CSV”的大技能。显式契约是说每个技能必须明确定义输入参数的类型、格式、是否必填以及输出的结构和可能的错误码。可组合性是说技能之间可以通过标准化的数据格式串联起来前一个技能的输出可以直接作为后一个技能的输入。2.2 技能注册与发现机制技能怎么被智能体找到这里有两种常见方案静态注册和动态发现。静态注册是在智能体启动时把所有技能加载到一个注册表里每个技能有一个唯一标识符和一段描述文本。智能体在规划阶段先读取注册表根据任务需求匹配技能。动态发现则是技能以独立服务的形式存在智能体通过某种协议去查询当前可用的技能列表。我实测下来对于大多数中小规模应用静态注册更简单也更可控。具体做法是维护一个skills.json或skills.yaml文件每个技能条目包含name、description、parameters、returns、examples这几个字段。智能体在收到用户请求后先把请求和技能描述做语义匹配选出候选技能再让模型判断调用顺序和参数填充。这里有个关键细节技能描述的质量直接决定匹配准确率。我见过很多项目把技能描述写成“处理数据”“执行操作”这种模糊表述结果模型根本不知道该在什么时候用它。好的描述应该包含动作、对象、前置条件和典型场景。比如“读取本地 CSV 文件并返回二维数组要求文件路径存在且为 UTF-8 编码适用于数据导入场景”就比“读 CSV”强得多。2.3 参数传递与状态管理技能之间传递数据是容易出问题的地方。最简单的做法是让每个技能返回一个字典下一个技能从字典里取需要的字段。但这样有个隐患如果前一个技能返回的字段名和后一个技能期望的不一致就会出错。agent-skills的做法是引入一个共享上下文对象所有技能都从这个上下文里读数据、往上下文里写数据技能之间不直接通信。这个上下文对象本质上是一个键值存储键是标准化的字段名值可以是任意类型。比如“读取文件”技能会把文件内容写到context[file_content]“解析 CSV”技能从context[file_content]读取内容解析后写到context[parsed_data]。这样做的好处是技能之间解耦了你可以替换掉“读取文件”的实现比如从本地读改成从网络读只要它仍然往context[file_content]写数据后面的技能完全不用改。注意共享上下文虽然方便但要注意字段命名冲突。建议给每个技能分配一个命名空间前缀比如csv_reader.output、csv_parser.input避免不同技能意外覆盖彼此的数据。3. 核心技能模块的拆解与实现要点3.1 文件操作类技能读、写、列目录文件操作是智能体最基础也最常用的技能。看起来简单但坑特别多。先说读文件核心参数是路径和编码方式。路径要处理绝对路径和相对路径的转换还要防止路径穿越攻击——如果用户输入../../etc/passwd这种路径技能必须拒绝执行。编码方式默认用 UTF-8但遇到 GBK 编码的文件要能自动检测或让用户指定。写文件技能的关键在于原子性。如果直接往目标文件写写到一半程序崩溃文件就损坏了。稳妥的做法是先写临时文件写完后用os.replace原子替换目标文件。另外要处理目录不存在的情况自动创建父目录。权限方面默认给 644 就行除非用户明确要求可执行。列目录技能返回文件列表时要包含文件名、大小、修改时间、是否为目录这些信息。我建议再加一个过滤参数支持按扩展名筛选这样智能体在找特定类型文件时不用把整个目录都拉回来再过滤。# 文件读取技能的核心逻辑示意 def read_file(path: str, encoding: str utf-8) - dict: # 路径安全校验 if .. in path or path.startswith(/): return {error: INVALID_PATH, message: 路径不合法} # 编码自动检测 if encoding auto: encoding detect_encoding(path) try: with open(path, r, encodingencoding) as f: content f.read() return {content: content, encoding: encoding, size: len(content)} except FileNotFoundError: return {error: FILE_NOT_FOUND, message: f文件 {path} 不存在} except UnicodeDecodeError: return {error: ENCODING_ERROR, message: 编码不匹配请指定正确编码}3.2 数据处理类技能解析、转换、聚合数据处理技能是智能体的“大脑”延伸。解析技能负责把原始文本转成结构化数据比如 CSV 转二维数组、JSON 转字典、XML 转树形结构。转换技能负责格式之间的互转比如把列表转成表格、把宽表转成长表。聚合技能负责分组统计、求和、求平均这些操作。这里有个设计决策用现成的库还是自己实现。我的建议是能用库就用库pandas 处理表格数据、json 处理 JSON、xml.etree 处理 XML这些库经过大量测试边界情况处理得比你自己写的好得多。但要注意库的版本兼容性以及大文件时的内存占用。如果数据量超过内存就得考虑流式处理或者分块读取。参数校验是数据处理技能的重中之重。比如聚合技能要检查分组字段是否存在、聚合字段是否为数值类型、聚合函数是否在支持列表里。我踩过的坑是用户传了一个空列表进来聚合技能直接除零报错。后来加了空数据检查返回一个明确的EMPTY_DATA错误码智能体就能根据这个错误码决定是提示用户还是走默认值。3.3 外部交互类技能网络请求与命令执行网络请求技能要处理超时、重试、状态码判断、响应解析这些事。超时默认设 10 秒重试最多 3 次每次间隔递增。状态码非 200 时返回错误信息不要把整个响应体都塞回去。响应解析支持 JSON 和文本两种模式JSON 模式要处理解析失败的情况。命令执行技能是最危险的一个必须严格限制可执行的命令白名单。我见过有项目直接让模型生成 shell 命令然后执行结果模型生成了一个rm -rf开头的命令幸好当时是在容器里跑的。稳妥的做法是只允许执行预定义好的几个命令模板参数通过占位符传入并且对参数做转义处理。提示命令执行技能一定要设置超时时间防止某个命令卡死导致整个智能体挂起。超时后要能强制终止子进程并清理临时文件。3.4 技能组合与编排模式单个技能再强也有限真正的威力在于组合。常见的编排模式有三种串行链、条件分支、循环迭代。串行链就是 A 完了 BB 完了 C适合线性流程。条件分支是根据前一个技能的输出决定下一步走哪条路比如文件存在就走读取不存在就走创建。循环迭代是对列表里的每个元素执行同一组技能比如批量处理多个文件。agent-skills里实现编排的方式是让智能体先生成一个执行计划计划是一个有序列表每个元素包含技能名和参数映射。参数映射支持引用前面步骤的输出比如{file_path: $step1.output.path}。执行器按顺序执行计划遇到错误就根据错误处理策略决定是中止还是跳过。这种方式的优点是计划可以被审查、被修改、被复用。你可以把常用的执行计划保存成模板下次遇到类似任务直接加载。缺点是计划生成阶段需要模型有较强的推理能力如果任务太复杂模型可能生成错误的计划。我的经验是给模型提供几个计划示例让它照着模仿准确率会高很多。4. 从零搭建一个技能化智能体的完整实操4.1 环境准备与依赖安装先确定技术栈。我推荐 Python 作为主力语言因为生态最全数据处理、网络请求、文件操作都有成熟的库。核心依赖包括pydantic用于参数校验和序列化pyyaml用于技能配置文件解析requests用于网络请求pandas用于表格数据处理。如果要做异步执行再加asyncio和aiohttp。目录结构这样组织skills/目录下每个技能一个文件文件名就是技能名。registry.py负责扫描skills/目录并加载所有技能。executor.py负责执行计划。context.py定义共享上下文对象。main.py是入口接收用户输入调用规划器生成计划再交给执行器。# 项目初始化 mkdir agent-skills-demo cd agent-skills-demo python -m venv venv source venv/bin/activate # Windows 用 venv\Scripts\activate pip install pydantic pyyaml requests pandas4.2 定义技能基类与注册表每个技能继承一个基类基类定义name、description、parameters、execute这四个必须实现的部分。parameters用 pydantic 的模型来定义这样自动获得类型校验和文档生成。execute方法接收参数字典和上下文对象返回结果字典。注册表的逻辑很简单遍历skills/目录下的所有.py文件用importlib动态导入找到继承自BaseSkill的类实例化后按name注册到字典里。同时生成一份技能描述列表供规划器使用。# registry.py 核心逻辑 import importlib, pkgutil, os from skills.base import BaseSkill class SkillRegistry: def __init__(self, skills_dirskills): self.skills {} self._load_skills(skills_dir) def _load_skills(self, skills_dir): for _, module_name, _ in pkgutil.iter_modules([skills_dir]): module importlib.import_module(f{skills_dir}.{module_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() self.skills[instance.name] instance def get_descriptions(self): return [{name: s.name, description: s.description, parameters: s.parameters.schema()} for s in self.skills.values()]4.3 实现三个基础技能并测试先实现最基础的三个read_file、parse_csv、write_file。read_file接收路径和编码返回内容。parse_csv接收内容和分隔符返回二维数组。write_file接收路径和内容写入文件。测试的时候不要一上来就接模型先用硬编码的计划跑一遍。比如计划是[read_file(pathdata.csv), parse_csv(content$step1.content), write_file(pathoutput.txt, content$step2.data)]手动构造这个计划看执行器能不能正确解析参数引用、按顺序执行、把结果串起来。这一步跑通了再接模型生成计划问题排查会容易很多。我实测中发现一个细节parse_csv返回的二维数组如果直接传给write_file写出来的是 Python 的列表字符串表示不是真正的 CSV 格式。所以中间还需要一个format_csv技能把二维数组转成 CSV 文本。这个技能很小但少了它整个链路就不完整。这也说明技能拆分要拆到“原子操作”级别不要指望一个技能既解析又格式化。4.4 接入规划器与执行器规划器的职责是接收用户请求和技能描述列表输出执行计划。最简单的实现是直接用大模型做 few-shot 推理给几个“请求→计划”的示例让模型照着生成。示例要覆盖常见场景单技能调用、串行链、条件分支。执行器按计划逐步执行每步做四件事从上下文解析参数引用、调用技能、检查返回是否有错误、把结果写回上下文。如果某步返回错误根据计划里定义的on_error策略处理abort直接中止skip跳过继续retry重试最多三次。# executor.py 核心逻辑 class Executor: def __init__(self, registry, context): self.registry registry self.context context def execute(self, plan): results [] for step in plan: skill self.registry.skills.get(step[skill]) if not skill: return {error: f技能 {step[skill]} 不存在} params self._resolve_params(step.get(params, {})) result skill.execute(params, self.context) if error in result: if step.get(on_error) skip: continue return result self.context[fstep_{len(results)}] result results.append(result) return {results: results} def _resolve_params(self, params): resolved {} for key, value in params.items(): if isinstance(value, str) and value.startswith($): ref value[1:].split(.) resolved[key] self.context.get(ref[0], {}).get(ref[1]) else: resolved[key] value return resolved4.5 完整案例自动生成数据摘要报告假设用户说“把 data 目录下所有 CSV 文件合并统计每列的平均值生成一份报告。”规划器生成的计划大概是列目录 → 过滤 CSV → 循环读取 → 合并 → 计算均值 → 格式化报告 → 写文件。这里循环迭代的处理比较特殊。我的做法是引入一个foreach技能它接收一个列表和一个子计划对列表里每个元素执行子计划。子计划里的参数可以用$item引用当前元素。这样就把循环逻辑封装在技能内部规划器只需要生成一次子计划。执行过程中上下文里会依次出现step_0目录列表、step_1CSV 文件列表、step_2合并后的数据、step_3均值结果、step_4报告文本、step_5写入结果。每一步的输出都可以被后续步骤引用整个链路清晰可追溯。实操心得在开发阶段把每一步的输入输出都打印出来方便定位问题。上线后再关掉日志或者只记录错误级别的日志。我习惯在上下文对象里加一个debug标志打开时记录所有读写操作。5. 常见问题与排查技巧实录5.1 技能匹配错误模型选了不该选的技能这是最常见的问题。用户说“整理一下数据”模型可能选了parse_csv也可能选了aggregate还可能选了format_table。根本原因是技能描述不够具体或者技能之间有重叠。解决办法有三个第一细化描述在描述里明确写出适用场景和不适用场景比如“本技能仅用于解析 CSV 格式文本不负责读取文件不负责数据计算”。第二加负面示例在技能配置里加一个not_for字段列出容易混淆的场景。第三加一层意图识别先用一个轻量模型判断用户意图属于哪个大类再在大类里匹配具体技能。我试过把技能描述从一句话扩展到包含“输入示例”“输出示例”“前置条件”“后置条件”的完整文档匹配准确率从 70% 提升到了 92%。虽然写描述的工作量大了但省下了大量调试时间。5.2 参数解析失败引用路径写错或数据不存在参数引用是$step_N.field这种格式常见错误包括步骤编号写错比如引用了$step_5但实际只有 4 步、字段名拼写错误、前一步返回了错误导致字段不存在。排查方法在解析参数时加详细的错误信息明确指出“引用了不存在的步骤 step_5”或“步骤 step_2 的返回中没有字段 content”。另外执行器应该在每步执行后检查返回结构是否符合技能定义的returns模式不符合就提前报错而不是等到下一步引用时才暴露。我踩过的一个坑是某个技能返回的字段名是data但我在计划里写的是result结果解析出来是None传给了下一个技能下一个技能又没做空值检查最后报了一个莫名其妙的错误。后来我在参数解析阶段加了空值检查如果解析结果是None且参数标记为必填直接报MISSING_PARAM错误。5.3 执行超时与资源耗尽网络请求技能和命令执行技能最容易超时。默认超时设 10 秒但对于大文件下载或复杂计算10 秒可能不够。我的做法是让技能自己声明一个timeout参数默认值写在技能配置里调用时可以覆盖。资源耗尽通常发生在循环迭代场景。如果列表有 1000 个元素每个元素执行 5 个技能总共 5000 次调用内存里会堆积大量中间结果。解决办法是引入流式处理循环技能不把所有结果都存在上下文里而是处理完一个就释放一个只保留聚合后的结果。或者设置一个最大迭代次数超过就报错。注意在容器环境里跑智能体时一定要设置内存和 CPU 限制。我见过一个死循环的计划把容器内存打满导致整个节点上的其他服务都受影响。5.4 技能版本更新导致的兼容性问题技能不是一成不变的。今天read_file返回content字段明天可能改成text字段。如果智能体还在用旧计划就会解析失败。解决办法是给技能加版本号计划里指定技能版本执行器加载对应版本的技能。或者更简单技能更新时保持向后兼容旧字段名保留但标记为废弃新字段名作为主要输出。我倾向于后者因为维护多版本技能的成本太高。具体做法是在技能基类里加一个deprecated_fields映射执行器在返回结果时自动把旧字段名映射到新字段名并打一条警告日志。等所有计划都更新后再移除旧字段。5.5 常见问题速查表问题现象可能原因排查方法解决措施技能匹配错误描述模糊或重叠打印候选技能列表和匹配分数细化描述加负面示例参数解析为 None引用路径错误检查步骤编号和字段名加空值检查和详细错误信息执行超时网络慢或计算量大打印每步耗时调整超时参数优化技能实现内存暴涨循环迭代堆积结果监控内存使用曲线流式处理限制迭代次数技能更新后计划失效字段名变更对比新旧返回结构保持向后兼容加废弃字段映射命令执行被拒绝白名单未包含检查命令是否在白名单内添加命令模板或调整白名单文件路径报错路径含特殊字符打印实际路径路径转义使用 pathlib 处理6. 技能体系的扩展方向与个人实践体会6.1 从单机技能到分布式技能当技能数量超过几十个或者某些技能需要特殊环境比如 GPU 计算、特定数据库连接单机加载所有技能就不现实了。这时候可以把技能拆成独立的微服务每个服务暴露一个 HTTP 接口智能体通过服务发现来调用。agent-skills的注册表可以扩展成支持远程技能技能描述里加一个endpoint字段执行器遇到远程技能就发 HTTP 请求而不是本地调用。这种架构的代价是延迟增加但换来了更好的隔离性和可扩展性。我建议在技能数量少、调用频率低的时候用单机方案等遇到性能瓶颈或环境依赖冲突时再考虑分布式。6.2 技能的市场化与复用技能做多了之后你会发现很多技能是通用的读文件、发邮件、查天气、调翻译。这些技能完全可以打包成标准组件在不同项目之间复用。我现在的做法是维护一个私有技能库每个技能有独立的版本号和变更日志新项目直接通过依赖管理工具引入。更进一步可以做一个技能市场让不同团队贡献和共享技能。但这需要一套完善的审核机制和沙箱环境防止恶意技能窃取数据或执行危险操作。目前我还没看到特别成熟的方案但方向是明确的。6.3 我在实际项目中的几点体会第一不要追求大而全的技能库。我一开始想做一个万能技能库结果每个技能都做得半吊子维护成本极高。后来砍掉了一半技能只保留最常用的十几个反而稳定了很多。技能不在多在于精和稳。第二错误处理比功能实现更重要。一个技能功能再强如果出错时返回的信息不明确排查起来就是噩梦。我现在写技能错误处理代码和功能代码的比例大概是 1:1每个可能的失败点都有明确的错误码和提示信息。第三文档和示例是技能的一部分。没有文档的技能等于没有技能因为别人不知道怎么用。我现在要求每个技能必须包含至少两个使用示例一个正常场景一个异常场景。这些示例同时用于测试和文档生成。第四定期审查执行日志。智能体跑一段时间后翻翻执行日志看看哪些技能调用失败率高、哪些参数经常传错、哪些计划执行时间过长。这些信息比任何性能测试都真实能直接指导优化方向。最后分享一个小技巧在技能执行前后加钩子函数可以统一做日志记录、性能统计、权限校验这些横切关注点。钩子函数注册在技能基类上所有技能自动继承。这样新增技能时不用重复写这些逻辑代码干净很多。