最近有朋友问我做智能体项目最怕遇到什么。我想了想不是模型不够聪明也不是算力不够而是每次新开一个智能体项目都要把那些重复的、底层的、通用的能力从头再写一遍——查一下可以换成“日常通知”“定时任务”“网页信息抓取”……换个需求就得重来。折腾多了你会意识到真正让智能体“好用”的不是某一个提示词写得多么精妙而是它能不能像人一样灵活调用一组稳定的、可复用的技能。这也是我最近在搞的一个项目“agent-skills”的出发点把智能体的能力拆成一个个可插拔、可复用的技能模块用一套轻量级的注册与调度机制让任何智能体都能按需取用。这篇文章我会从设计思路、核心技术点、实际操作到踩坑经验完整拆一遍。如果你正在做基于大模型的智能体应用或者准备给现有Agent加能力扩展这篇内容应该能帮你省不少时间。1. 项目核心思路拆解为什么智能体需要“技能库”1.1 单体提示词的问题在哪先说个场景。你想做一个个人助理智能体要求它能查天气、能读PDF、能定时提醒、能搜索网页。很多人的第一版做法是把这些需求全部塞进系统提示词里然后在Prompt里描述“当用户提到天气时你调用xxx当用户上传PDF时你先抽取文本再总结”。这种做法在小规模demo阶段是可以跑的但只要需求一多问题立刻出现提示词越来越长模型越容易“漏读”工具指令新增一个能力就要改一遍Prompt还要重新测试旧功能是否受影响更麻烦的是当多个任务需要按顺序执行时纯靠Prompt里的文字约束模型的执行稳定性会明显下降。打个比方你把所有技能都堆在一个人的脑子里让他同时当厨师、司机、会计还要记住每件事的触发条件——他不当场宕机才怪。1.2 从“插件”到“技能”的范式转变业界其实已经有过几轮探索。第一波是插件化把能力拆成独立插件按需加载。这个思路清晰但问题在于插件与平台绑定太深换个框架基本就得重写。第二波是Function Calling让模型根据函数定义去选择并生成调用参数。这解决了“模型主动选工具”的问题但它本质上是“函数”不是“技能”——一个技能往往需要串起多个函数调用还要包含前置校验、异常处理、结果格式化等逻辑。“agent-skills”的思路是把“技能”作为第一公民而不是把函数作为第一公民。一个技能本质上是一个完整的、可独立执行的能力单元它包含触发条件什么时候该用、入参定义需要哪些信息、执行逻辑内部调用哪些函数/模型/API、输出规范结果如何返回给智能体。技能之间可以互相调用也可以被多个不同场景复用。这样智能体的核心工作只剩下一件判断当前任务需要哪些技能然后按顺序把技能调度起来。1.3 agent-skills 的核心设计原则我设计这套体系时给自己定了三条原则也是在后面所有实现中反复校验的底线。第一技能必须自描述。也就是说技能文件本身要能回答四个问题我是什么、我什么时候被调用、调用我需要什么参数、我会返回什么。只有做到自描述模型才能在没有额外配置的情况下通过技能名单与描述来正确选择技能。第二运行时隔离。技能的加载、执行、报错都不能影响主智能体的运行。一个技能崩溃了不能拖着整个Agent一起挂掉。这在实际生产环境特别重要因为真实任务里一个外部API超时、一个PDF解析出错都是正常情况智能体需要从错误中恢复或换一条路而不是直接“死机”。第三组合优于继承。技能之间不是继承关系而是组合关系。比如“月度报告生成”这个技能内部可以组合“数据查询”“文档模板渲染”“图表绘制”三个基础技能。你不必为每一个业务场景单独写一套逻辑只要把基础技能组合好就能得到新能力。2. 核心细节解析与实操要点技能如何定义、注册、运行2.1 技能定义格式一份SKILL.md加一个执行体关于“技能长什么样”我参考了大量成熟方案最终沉淀成“SKILL.md清单可执行体”的双文件结构。SKILL.md负责描述技能元信息执行体Python脚本、Shell命令、API调用均可负责真正干活。SKILL.md的核心字段我用YAML格式维护因为YAML易读也方便直接喂给大模型做语义理解。name: web_search description: 当用户需要查询最新信息、事实核查、查找网址时使用。 parameters: query: type: string description: 搜索关键词或自然语言查询内容。 required: true top_k: type: integer description: 返回结果数量默认5。 required: false output: type: list description: 返回包含标题、摘要、URL的搜索结果列表。 timeout: 30这里的关键点是description字段它必须写清楚“什么时候该用”而不是“这个技能能做什么”。原因在于大模型做技能选择时本质上做的是一个语义匹配它靠你的描述来判断当前用户意图是否匹配这个技能。描述写得越贴近用户口语模型选得越准。很多人在这一步偷懒写“网页搜索功能”结果模型经常在需要搜索时选择了别的技能。执行体我统一封装成标准输入输出。无论是Python脚本、Node脚本还是一个HTTP请求最终都要变成“接收JSON入参返回JSON结果”的形态。这是为了让调度层不关心技能内部实现语言只要执行体遵守这个契约就能接入。2.2 技能注册与发现机制有了技能定义文件还需要一套注册机制把它们变成运行时可见的“技能清单”。我采用目录扫描加延迟加载的策略每个技能放在独立目录下里面有SKILL.md和executable文件系统启动时只扫描并解析SKILL.md构建技能索引真正执行时才加载对应执行体。这个设计考虑是启动阶段如果把所有技能的执行体都加载进来内存和启动时间都会增加二三十个技能但实际一次任务里可能用到的只有三四个。延迟加载让系统轻量也让技能升级时不需要重启整个Agent热替换技能目录即可。技能索引构建完成之后Agent会拿到一份所有可用技能的“简历”——也就是每个技能的name、description和parameters。在每次对话的推理阶段模型基于这份清单结合用户当前输入选出需要调用的技能及参数。选错了怎么办在有真实反馈的训练/评测环境里可以把这个选错样本记录下来用来微调技能描述或模型决策逻辑在纯在线推理环境里则要靠“模型可以重新选择技能”的循环容错机制兜底。2.3 技能执行与结果返回的约定技能执行器Executor负责加载并运行技能。我建议统一做三层处理入参校验、运行时隔离、结果规范化。入参校验基于SKILL.md里parameters的JSON Schema在执行前强制校验缺少必填参数就直接报错不进入执行阶段。这样能过滤掉很多“模型幻觉参数”也方便排查问题。运行时隔离用子进程执行这样技能就算因为外部依赖死循环或者内存泄漏也不会拖垮Agent主进程超时就直接kill。结果规范化则是把技能返回的原始输出统一包装成Agent能够理解的结构。{ status: success, data: { items: [] }, meta: { execution_time_ms: 320, skill_name: web_search } }这个包装结构非常重要因为大模型需要明确知道“这个技能到底成功没有”。很多Agent失效不是模型不行而是技能返回值没有明确的成功/失败信号模型只能靠猜。3. 工具选型与项目结构推荐3.1 为什么主语言选Python主语言我选Python没有悬念。一是大模型生态几乎都在Python接入各种模型API、Embedding、向量库最顺滑二是技能执行体最常见的形态就是Python脚本大家都能写三是多进程管理、信号超时控制这些运行时特性在Python里心智负担最低。如果你们团队更熟悉Node.js也可以实现同样思路但Python在“技能脚本大模型能力”场景下确实最省事。3.2 项目目录结构参考我用的目录结构长这样简单直接适合中小团队快速起步。agent-skills/ ├── skills/ │ ├── web_search/ │ │ ├── SKILL.md │ │ └── run.py │ ├── read_pdf/ │ │ ├── SKILL.md │ │ └── run.py │ └── schedule_event/ │ ├── SKILL.md │ └── run.py ├── core/ │ ├── registry.py # 技能注册与索引 │ ├── executor.py # 技能执行器 │ └── schema_validator.py ├── agent/ │ └── agent_loop.py # 主智能体调度循环 ├── config.yaml └── requirements.txt这个结构把技能本身和核心机制分开了。新来的同事要加技能只需要在skills/下新建目录写清楚SKILL.md和run.py其他什么都不用改。这就是“可插拔”的意义团队协作时不同人维护不同技能互不干扰。3.3 核心依赖清单依赖方面我尽量精简能少一个就少一个因为技能执行环境被依赖绑架越深迁移成本越高。依赖用途openai / anthropic SDK接入大模型服务pydantic参数校验与结果规范化pyyaml解析SKILL.mdrequests技能内外部API调用multiprocessing标准库子进程隔离执行技能这里插一句我不建议一上来就引入重型Agent框架。你可以用框架来管理对话状态、多轮记忆但技能调度这部分最好自己实现这样你能完全掌控技能选择的逻辑和错误反馈路径排查问题时不至于黑盒。4. 实操过程与核心环节实现从零搭建一个技能库4.1 第一步定义技能注册器注册器是整个技能库的入口负责扫描目录、读取元信息、提供查询接口。我的实现里核心类长这样# core/registry.py import yaml from dataclasses import dataclass, field from pathlib import Path from typing import Dict, List dataclass class SkillMeta: name: str description: str parameters: dict output: dict timeout: int 30 path: Path None class SkillRegistry: def __init__(self, skill_dir: str skills): self.skill_dir Path(skill_dir) self._skill_metas: Dict[str, SkillMeta] {} def scan(self): for skill_path in self.skill_dir.iterdir(): meta_file skill_path / SKILL.md if not meta_file.exists(): continue meta self._parse_meta(meta_file, skill_path) self._skill_metas[meta.name] meta return self._skill_metas def _parse_meta(self, meta_file: Path, skill_path: Path) - SkillMeta: with open(meta_file, r, encodingutf-8) as f: raw yaml.safe_load(f) raw[path] skill_path return SkillMeta(**raw) def get_all_meta(self) - List[dict]: # 转为纯文本描述给模型做技能选择 return [ {name: m.name, description: m.description, parameters: m.parameters} for m in self._skill_metas.values() ] def get_meta(self, name: str) - SkillMeta: return self._skill_metas.get(name)这个注册器不绑定任何具体模型也不关心技能内部怎么实现。它只负责一件事把技能变成“可被模型理解的元信息集合”。你在实现时要注意Paths和相对路径的处理不要用绝对路径写死技能目录否则项目换个位置就全废了。4.2 第二步编写技能执行器执行器负责真正的跑腿工作。我的实现里每个技能会用子进程方式运行并包裹一个超时控制。这样单个技能卡死不会影响主进程。# core/executor.py import json import multiprocessing from typing import Any, Callable def _run_target(skill_path: str, params: dict, result_dict: dict): try: # 动态加载技能模块 import importlib.util spec importlib.util.spec_from_file_location(skill_run, f{skill_path}/run.py) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) result module.run(**params) result_dict[success] True result_dict[data] result except Exception as e: result_dict[success] False result_dict[error] str(e) class SkillExecutor: def __init__(self, registry): self.registry registry def execute(self, skill_name: str, params: dict) - dict: meta self.registry.get_meta(skill_name) timeout meta.timeout if meta else 30 manager multiprocessing.Manager() result_dict manager.dict() p multiprocessing.Process( target_run_target, args(str(meta.path), params, result_dict) ) p.start() p.join(timeout) if p.is_alive(): p.terminate() return {status: timeout, error: fskill exceeded {timeout}s} if not result_dict.get(success): return {status: error, error: result_dict.get(error, unknown)} return {status: success, data: result_dict.get(data)}这里最容易踩的坑是multiprocessing.Manager在Windows上运行会有些怪异比如必须放在ifname main保护下才能跑。如果你只是在Linux服务器上部署大概率没事但本地开发若是Windows环境建议直接用subprocess的方式执行脚本。4.3 第三步写一个能用的技能作为样例光有框架不够直接写一个实际技能来验证。我拿“时间查询”和“网页Fetch”来演示因为它们足够简单逻辑清晰。时间查询技能# skills/get_current_time/run.py from datetime import datetime from zoneinfo import ZoneInfo def run(timezone: str Asia/Shanghai, format: str %Y-%m-%d %H:%M:%S): if timezone not in [ Asia/Shanghai, America/New_York, Europe/London, Asia/Tokyo ]: raise ValueError(f不支持的时区: {timezone}) now datetime.now(ZoneInfo(timezone)) return {timezone: timezone, current_time: now.strftime(format)}网页Fetch技能# skills/fetch_page/run.py import requests from bs4 import BeautifulSoup def run(url: str, max_length: int 5000): resp requests.get(url, timeout15, headers{ User-Agent: Mozilla/5.0 (compatible; agent-skills/1.0) }) resp.raise_for_status() soup BeautifulSoup(resp.text, html.parser) for tag in soup([script, style, nav, footer]): tag.decompose() text soup.get_text(separator\n, stripTrue) return {url: url, content: text[:max_length]}这种简单技能的价值在于跑通整条链路。等到链路稳定了你再往里加业务复杂度就顺理成章。4.4 第四步主智能体调度循环最后是Agent主循环。这里我使用一个非常朴素的思路先构建技能清单然后把用户请求和技能清单一起发给大模型让模型返回“调用哪个技能、传什么参数”再执行技能把结果返回给模型做最终回答。# agent/agent_loop.py import json from core.registry import SkillRegistry from core.executor import SkillExecutor SYSTEM_PROMPT_TEMPLATE 你是一个智能助手可以调用以下技能来完成任务。 技能列表 {skill_descriptions} 当用户请求需要调用技能时请严格输出一段JSON {{skill: 技能名, params: {{...}}}} 不要输出其他文字。 class AgentLoop: def __init__(self, llm_client): self.registry SkillRegistry() self.registry.scan() self.executor SkillExecutor(self.registry) self.llm llm_client def _build_system_prompt(self): skills self.registry.get_all_meta() desc \n.join([f- {s[name]}: {s[description]} for s in skills]) return SYSTEM_PROMPT_TEMPLATE.format(skill_descriptionsdesc) def run(self, user_input: str): messages [ {role: system, content: self._build_system_prompt()}, {role: user, content: user_input}, ] response self.llm.chat(messagesmessages) content response.content.strip() try: cmd json.loads(content) skill cmd.get(skill) params cmd.get(params, {}) except json.JSONDecodeError: # 模型没有调用技能直接返回原始回答 return content, None result self.executor.execute(skill, params) messages.append({role: assistant, content: content}) messages.append({role: user, content: f技能执行结果: {json.dumps(result)}}) final_response self.llm.chat(messagesmessages) return final_response.content, result这段代码非常简化但已经能跑通“用户提问—模型选技能—执行技能—整理结果”的完整闭环。生产环境里你会需要加入多轮上下文管理、记忆持久化、技能选择置信度判断等但核心骨架就是这几行。4.5 技能编排让一个技能调用另一个技能这里再展开一个关键升级。一个强大的技能体系不能只有“一对一”的原子技能还得支持组合编排。比如你想让智能体能回答“帮我查一下今天上海的天气然后顺便订一个适合户外活动的推荐方案”这至少涉及天气查询、活动推荐两个技能。我的做法是给技能执行链加一个“编排层”。编排层不直接执行技能而是把一个大目标拆成“技能依赖图”依次执行。具体可以用一个简单的Python流程控制或用Step Functions、LangGraph这类现成工具。这里我推荐先手工写编排逻辑不要急着上框架因为你还没摸清自己场景里的依赖关系框架只会给你增加抽象负担。def weather_activity_plan(city: str): weather executor.execute(get_weather, {city: city}) if weather[status] ! success: return {error: 天气查询失败} suggestion executor.execute( activity_suggestion, {city: city, condition: weather[data][condition]} ) return {weather: weather[data], suggestion: suggestion[data]}这种函数式编排最大的好处是“可读”。出问题时你能一步步追踪不会整个链路的上下文都藏在框架内部。5. 常见问题与排查技巧实录5.1 典型问题速查表在我实际跑这个项目以及帮别人review代码的过程中下面几个问题出现过非常多次我先直接列成表格省得你踩了坑再回头看。问题现象根本原因解决方案模型经常选错技能SKILL.md里description写得太抽象模型无法准确匹配用户口语意图重写description用“当用户想xxx时”句式加入用户可能的原话例子技能执行报超时技能内部同步调用外部API没做超时控制执行器外层加timeout同时技能内部对requests也设置timeout参数老是被传错模型对parameters里的description理解不足给每个参数增加正反例描述比如“query: 应填入完整的搜索关键词不要截断”某个技能出错导致整个Agent中断没有做运行时隔离技能异常向上传播使用子进程或subprocess执行每个技能包一层异常捕获技能升级后老版本还在跑注册器缓存了技能Meta或模块引用每次执行时检查技能目录的mtime变更后重新加载Meta执行体不要直接import固定路径模块多技能编排时上下文丢失编排中间结果没有拼回主对话上下文每个技能返回后立即把结果append到messages让模型始终感知全局5.2 技能描述的重写经验关于技能描述我想多说两句。这是我调试智能体时花时间最多、回报最明显的地方。一开始我写的技能描述偏向“系统工程师视角”比如“获取指定Web页面的HTML内容并提取主要文本”。模型在简单场景下能选对但只要用户表达稍微口语化一点比如“你帮我搜下这篇文章到底讲了啥”模型就可能在多个技能之间犹豫。后来我改用“用户动机视角”重写当用户想了解某个网页内容、对文章做摘要、或者提到某个链接让他看看时使用。这里的URL可以是用户直接粘贴的完整地址也可以是从搜索结果中得到的链接。同样的技能描述方式换了一下技能选择准确率肉眼可见地上来了。核心逻辑是大模型是根据语义相似度匹配技能和意图的你的描述越接近用户在聊天框里实际说的话匹配越准。5.3 关于技能执行环境依赖的心得另一个容易被低估的问题是技能运行环境。不同技能的第三方依赖经常产生版本冲突。比如一个技能要pandas 1.5另一个技能要pandas 2.0装在一起世界就会崩塌。我建议有条件的话给每个技能单独建虚拟环境或者用容器方案来跑代价是执行时延会增加几十毫秒但换来的是环境隔离和稳定性。如果项目还在早期图省事那就统一用一个环境但要在SKILL.md的元信息里把依赖写清楚并且尽量用兼容范围宽的依赖版本号。还有一个细节技能脚本里的第三方库导入尽量放到函数内部不要让run()导入前就执行模块级别的import。这样即使某个技能依赖缺失也只是在真正执行到该技能时报错不影响Agent启动时扫描其他技能。6. 生产环境里更进阶的几件事6.1 技能版本与评估技能一旦多起来就不能靠“拍脑袋”判断改动是否有效。我建议给每个技能建立基准测试集合里面保存20到30条典型用户请求和期望的技能调用结果。每改一次技能描述或执行逻辑就跑一遍基准集看改变了多少样本的选择结果和最终成功率。没有这套机制你很难判断这次技能优化到底是在进步还是在开倒车。6.2 技能选择的“置信度兜底”还有一类失败的场景是模型死活选不出技能或者选了一个不太相关的技能。为了兜底我在Agent循环里加了一层“低置信度重选”机制——当技能执行结果与用户问题明显不匹配时把执行结果和错误信息附加上让模型再做一轮判断允许它换一个技能重试。这个循环最多执行两次防止掉进无限重试的坑。6.3 把技能做成团队资产最后聊点长期的。技能库的价值随着时间累积会越滚越大而不是越滚越乱。关键是要把它当成团队资产来经营。我见过很多团队技能目录变成了垃圾堆没文档、没测试、没owner。我建议至少在技能目录里维护一份README记录每个技能的维护人、最近改动、依赖项。这样技能库才真的能从“个人脚本集”变成“组织能力库”。我个人在这套体系里摸索大半年后最大的体会是Agent项目到最后拼的根本不是模型而是你如何体系化地组织技能、控制边界、让能力可复用且可维护。你把“技能库”这件事做到位不管是接新场景还是加新需求都只是往里面插一块新积木而不是推倒重来。
