1. 从“会聊天”到“能干活”agent-skills 到底在解决什么问题如果你最近半年一直在折腾大模型应用大概率会有一种强烈的割裂感模型在对话框里上知天文下知地理可一旦让它去真实环境里干点活——读一份本地表格、调一个内部接口、按流程走完三步审批——它立刻就开始胡言乱语要么编一个不存在的函数名要么把参数顺序搞反要么干脆假装自己已经执行完了。这个落差就是agent-skills这类项目要填的坑。所谓 agent-skills直译过来就是“智能体技能”它指的是一套让大模型从“只会说”变成“能动手”的能力封装体系。你可以把它理解成给一个聪明但四肢不协调的人配上一整套标准化的工具手柄螺丝刀、扳手、电钻各就各位每个工具上还贴了使用说明和力矩参数。模型负责判断“现在该拧螺丝”而 agent-skills 负责保证“拧的时候用对工具、用对力度、不会把螺纹拧滑”。它解决的问题非常具体。第一是能力边界问题模型本身只会输出文本agent-skills 把外部世界的能力读写文件、发请求、查数据库、跑脚本抽象成模型能理解的描述。第二是调用可靠性问题光有工具不够还得规定什么时候调、参数怎么填、失败了怎么办。第三是可维护性问题一堆散落的函数调用逻辑过两个月自己都看不懂agent-skills 用统一的注册、描述、执行机制把它们管起来。适合看这篇内容的人我大致分三类。一类是刚接触智能体开发、被各种框架名词绕晕的新手想搞清楚“技能”这个抽象到底落在代码的哪一层。一类是已经用过大模型接口、但调用逻辑写得一团乱麻的开发者想找一套能长期维护的组织方式。还有一类是产品或者项目负责人想评估“让模型自动干活”这件事到底靠不靠谱、坑在哪里。不管你是哪一类接下来的内容都会从设计思路一路讲到实操细节和踩坑记录尽量让你看完就能上手改自己的项目。2. 整体设计思路为什么“技能”要单独抽一层2.1 核心矛盾模型很聪明但接口很笨要理解 agent-skills 的设计得先认清一个现实大模型本质上是一个文本到文本的函数。你给它一段话它还你一段话。它没有内存指针没有文件句柄没有网络套接字。所有“操作外部世界”的能力都必须通过某种方式“翻译”成文本让模型去生成再由外部程序去执行。最原始的做法是这样的你在提示词里写“如果用户想查天气就输出get_weather(城市名)”然后自己在代码里用字符串匹配去解析。这个做法在只有一两个功能时能跑但功能一多就崩了。原因很简单——模型输出的格式不稳定今天写get_weather(北京)明天写查询天气北京你的解析代码永远追不上它的花样。agent-skills 的第一个设计决策就是把“技能”定义成一个有明确契约的对象。这个契约至少包含三部分技能的名字和描述给模型看的、参数的名称和类型给模型填的、真正的执行函数给程序跑的。模型不再自由发挥而是在一个受约束的菜单里点菜。这就像你去餐厅以前是跟厨师说“随便来个好吃的”现在是看菜单点“宫保鸡丁微辣不要花生”。后者出错的概率低得多。2.2 方案选型注册表模式 vs 硬编码分支在具体实现上常见的有两条路。一条是硬编码分支在主流程里写一堆if 意图 查天气: ... elif 意图 发邮件: ...。另一条是注册表模式每个技能自己声明元信息统一注册到一个中心表里主流程只负责“查表—调用”。我强烈建议走注册表这条路理由有三个。第一扩展成本。加一个新技能硬编码方式要改主流程、加分支、重新测试整条链路注册表方式只需要新增一个技能文件主流程一行不动。第二描述一致性。注册表能保证每个技能都以同样的格式暴露给模型模型看到的“菜单”是整齐的理解成本低。第三可测试性。每个技能是独立单元可以单独写测试不用把整个智能体跑起来。这里有个容易被忽略的点技能的描述文本本身就是提示词的一部分。很多人写技能描述特别敷衍就写“查询天气”。模型看到这四个字根本不知道参数该传城市名还是城市代码也不知道返回的是摄氏度还是华氏度。好的描述应该像给一个新员工写操作手册把“什么时候用、参数是什么、返回什么、有什么限制”都写清楚。这部分后面会专门展开。2.3 执行链路一次技能调用到底经历了什么把整个链路拆开看一次成功的技能调用大致经过这几个阶段。用户输入进来模型结合系统提示词和技能清单判断是否需要调用技能。如果需要模型输出一个结构化的调用请求包含技能名和参数。外部程序解析这个请求在注册表里找到对应技能做参数校验。校验通过后执行真正的函数拿到结果。结果再被塞回对话上下文模型基于结果生成最终回复。这条链路里参数校验是最容易被跳过、也最容易出事的一环。模型填参数时可能把数字填成字符串可能漏掉必填项可能传一个超出范围的枚举值。如果不校验直接执行轻则报错重则产生副作用比如删错文件。所以一个成熟的 agent-skills 实现一定会在执行前做类型检查和边界检查校验失败时把错误信息返回给模型让它自己纠正重试。提示校验失败的信息要写得对模型友好。不要返回“ValueError: invalid literal”而要返回“参数 city 必须是字符串类型的城市名称你传的是数字 123请重新填写”。模型看到后者才知道怎么改。3. 核心细节解析一个技能对象该长什么样3.1 技能元信息的四个必备字段不管用什么语言实现一个技能对象的元信息至少要有这四个字段缺一个都会在某个环节出问题。name技能名这是模型调用时用的唯一标识。命名建议用动词加名词的小写下划线格式比如read_file、send_email、query_order。不要用中文不要用空格不要用驼峰。原因很实际——模型在生成调用时下划线格式的稳定性明显高于其他格式而且很多解析库对下划线友好。description描述这是给模型看的说明书也是整个技能体系里最需要花心思的地方。我的一般写法是“功能一句话 使用场景 参数说明 返回说明 注意事项”。举个例子一个读文件的技能描述可以这样写“读取指定路径的文本文件内容。当用户需要查看某个文件里写了什么时使用。参数 path 是文件的完整路径必须是字符串。返回文件内容的字符串。如果文件不存在会返回错误信息此时不要重试直接告诉用户文件不存在。”这段描述比“读取文件”四个字的信息量大了十倍模型调用准确率会有肉眼可见的提升。parameters参数定义通常用 JSON Schema 来描述每个参数标明类型、是否必填、含义。类型尽量用基础类型string、number、boolean、array避免嵌套过深。如果某个参数只能是几个固定值之一一定要用枚举enum约束住这能挡掉大量无效输入。handler执行函数真正干活的代码。这个函数应该保持“纯”一点——输入参数输出结果尽量不依赖全局状态。副作用写文件、发请求可以有但要可控、可回滚、有日志。3.2 参数设计里的三个反直觉经验参数设计看起来简单实际踩坑最多。分享三个我踩出来的经验。第一个经验参数越少越好但该拆的要拆。有人喜欢把所有东西塞进一个options对象里模型填起来容易漏字段。也有人喜欢把日期拆成 year、month、day 三个参数模型反而容易填错。我的判断标准是如果两个参数总是一起出现、一起变化就合并如果一个参数有独立的语义和校验规则就拆开。日期这种直接用一个 ISO 格式的字符串参数最省事。第二个经验给参数起名要“望文生义”。path比p好start_date比sd好。模型在填参数时参数名本身就是重要的语义线索。你写sd它可能理解成“标准差”也可能理解成“开始日期”纯靠猜。写全了准确率立刻上去。第三个经验默认值要慎用。给参数设默认值看起来方便但模型一旦发现“这个参数可以不填”就倾向于不填然后依赖默认值。如果默认值不符合当前场景就会出隐蔽的 bug。我的做法是只有真正无关紧要的参数才给默认值核心参数一律必填逼模型想清楚。3.3 返回值处理别把原始数据直接丢回去技能执行完返回值怎么给模型也是个技术活。最常见的错误是把原始数据比如一整张数据库表、一个巨大的 JSON直接塞回上下文。这会导致两个问题上下文被撑爆以及模型被无关信息干扰。正确的做法是做一层结果摘要。比如查询订单返回了 50 条记录不要全塞回去而是返回“共查到 50 条订单前 3 条是……”。如果模型需要更多让它再调一次带分页参数的技能。这就像你问助理“公司有多少人”他应该回答“大概两百人”而不是把员工名册整个背给你听。另外错误也要作为一种正常返回值。技能执行失败时不要抛异常中断整个流程而是返回一个结构化的错误对象包含错误类型和给模型的建议。模型拿到错误后可以选择重试、换参数、或者告诉用户。把错误处理交给模型比在代码里写死一堆 catch 分支灵活得多。4. 实操过程从零搭一个可用的技能体系4.1 环境准备与目录结构假设我们用 Python 来搭这套东西依赖其实很少核心就是大模型的 SDK 加一个 JSON 处理库。目录结构我建议这样组织agent_project/ skills/ __init__.py registry.py # 注册表核心逻辑 file_skills.py # 文件相关技能 net_skills.py # 网络相关技能 agent.py # 主流程 config.py # 配置把技能按领域分文件每个文件里定义若干技能最后统一注册。这样找起来方便也方便按需加载——有些技能涉及敏感操作可以只在特定场景下注册。4.2 注册表的核心实现注册表本身不复杂核心就是一个字典加两个方法注册和查找。但有几个细节要处理好。注册时要做重名检查两个技能叫同一个名字后注册的会覆盖前面的这种 bug 很隐蔽。查找时要处理“技能不存在”的情况返回明确的错误而不是抛 KeyError。class SkillRegistry: def __init__(self): self._skills {} def register(self, name, description, parameters, handler): if name in self._skills: raise ValueError(f技能 {name} 已存在请检查是否重复注册) self._skills[name] { name: name, description: description, parameters: parameters, handler: handler, } def get(self, name): return self._skills.get(name) def list_for_model(self): # 转成模型能理解的格式通常是 JSON 数组 return [ { name: s[name], description: s[description], parameters: s[parameters], } for s in self._skills.values() ]这段代码短但它是整个体系的骨架。list_for_model返回的结构会直接拼进系统提示词所以格式要稳定。4.3 写第一个技能读取本地文本文件拿一个最实用的技能开刀——读文件。这个技能看起来简单但把参数校验、错误处理、结果摘要都覆盖到了很适合当模板。import os def read_file_handler(path: str) - str: if not isinstance(path, str): return {error: 参数 path 必须是字符串} if not os.path.exists(path): return {error: f文件 {path} 不存在请确认路径是否正确} if os.path.getsize(path) 1024 * 1024: return {error: 文件超过 1MB请改用分段读取技能} with open(path, r, encodingutf-8) as f: content f.read() # 结果摘要太长的内容截断 if len(content) 4000: return {content: content[:4000], truncated: True, note: 内容过长已截断如需完整内容请分段读取} return {content: content, truncated: False}注册的时候描述要写清楚registry.register( nameread_file, description读取指定路径的文本文件内容。当用户需要查看某个文件里写了什么时使用。 参数 path 是文件的完整路径必须是字符串。 返回文件内容如果内容过长会被截断。 如果文件不存在会返回错误此时不要重试直接告诉用户。, parameters{ type: object, properties: { path: {type: string, description: 文件的完整路径} }, required: [path] }, handlerread_file_handler )注意描述里那句“此时不要重试直接告诉用户”。这句话是专门写给模型看的能有效减少它拿到错误后反复重试同一个不存在文件的行为。这种“行为约束”写在描述里比写在代码里管用。4.4 主流程把技能清单喂给模型主流程要做的事是把技能清单转成提示词的一部分然后处理模型的调用请求。这里的关键是调用请求的解析要宽容。模型输出的格式可能不完全标准比如多了一层引号、少了一个括号。解析时要做容错能修就修修不了再报错。def build_system_prompt(registry): skills_json json.dumps(registry.list_for_model(), ensure_asciiFalse, indent2) return f你是一个可以调用工具的智能体。 可用技能如下 {skills_json} 当需要调用技能时输出如下格式的 JSON {{skill: 技能名, arguments: {{参数名: 参数值}}}} 不需要调用技能时直接回答用户。主循环里拿到模型输出后先尝试解析成 JSON。解析成功且技能存在就执行执行结果塞回对话解析失败就把错误信息返回给模型让它重新输出。这个循环通常设一个最大轮次比如 5 轮防止模型陷入死循环。4.5 参数校验的落地写法参数校验我建议单独抽一个函数因为每个技能都要用。核心是检查必填项、检查类型、检查枚举值。def validate_args(schema, args): props schema.get(properties, {}) required schema.get(required, []) for key in required: if key not in args: return f缺少必填参数 {key} for key, value in args.items(): if key not in props: return f未知参数 {key} expected props[key].get(type) if expected string and not isinstance(value, str): return f参数 {key} 应为字符串实际是 {type(value).__name__} if expected number and not isinstance(value, (int, float)): return f参数 {key} 应为数字 if enum in props[key] and value not in props[key][enum]: return f参数 {key} 只能是 {props[key][enum]} 之一 return None校验失败时把返回的错误字符串原样塞回给模型它下一轮通常就能改对。实测下来加了这层校验之后技能调用的成功率能从六七成提到九成以上。5. 常见问题与排查技巧实录5.1 模型不调用技能只在那聊天这是新手遇到最多的一个问题。用户明明说了“帮我读一下那个文件”模型却回一句“好的请告诉我文件路径”然后就没有然后了。原因通常有三个。一是技能描述写得太模糊模型没意识到这个技能就是干这个的。二是系统提示词里没有明确要求“需要操作时优先调用技能”。三是模型本身的能力问题小参数模型对工具调用的理解确实弱一些。排查顺序我一般是这样先看技能描述把“当用户需要……时使用”这种触发条件写进去再看系统提示词加一句“如果用户的请求可以通过技能完成必须调用技能不要只做口头承诺”最后如果还不行考虑换一个对工具调用支持更好的模型。前两步能解决八成问题。5.2 参数总是填错或者漏填参数问题的根源九成在描述上。我整理了一个对照表左边是常见错误右边是修法。现象可能原因修法漏填必填参数描述里没强调必填在参数描述里写“必填”类型填错参数名有歧义改成望文生义的名字枚举值填错没给枚举约束加 enum 限制日期格式乱没规定格式描述里写明“ISO 格式如 2024-01-01”路径填相对路径没说明要绝对路径描述里写“必须是绝对路径”这张表我贴在显示器边上每次写新技能都对照一遍能省下大量调试时间。5.3 技能执行成功但模型理解错了结果有时候技能明明返回了正确数据模型却给出了错误结论。比如技能返回“库存 0”模型却说“还有货”。这通常是返回值的结构不清晰导致的。模型看到一堆字段不知道哪个是关键。解决办法是让返回值自带语义。不要返回{stock: 0}而是返回{stock: 0, status: 缺货, message: 该商品当前无库存}。把结论直接写在返回值里模型就不用猜了。这个技巧看起来笨但极其有效。5.4 多个技能冲突或者循环调用当技能数量多起来模型可能选错技能或者在两个技能之间来回跳。比如先调search再调read再调search陷入循环。防循环的手段有两个一是设最大调用轮次超过就强制结束并返回当前结果二是在系统提示词里写明“同一个技能不要连续调用超过两次如果两次都没拿到有用信息直接告诉用户”。技能冲突则要靠描述来区分。如果两个技能功能相近一定要在描述里写清楚各自的适用场景和区别。比如search_web和search_local描述里要明确一个是搜互联网、一个是搜本地库别让模型自己猜。5.5 排查速查表问题首选排查点快速验证方法不调用技能技能描述触发条件手动在提示词里加“必须调用”参数错误参数名和类型描述打印模型原始输出看它填了什么结果理解错返回值语义在返回值里加 message 字段循环调用最大轮次设置日志里数调用次数技能选错描述区分度把两个技能描述并排对比注意调试阶段一定要把模型的原始输出完整打日志包括它生成的调用 JSON。很多人只看最终回复结果问题出在中间那步调用上白白绕远路。6. 技能体系的扩展与长期维护6.1 技能分组与按需加载技能一多全量塞给模型会撑爆上下文也会降低选择准确率。我的做法是按场景分组。比如“文件操作组”“网络请求组”“数据处理组”每次只把当前场景相关的组加载进去。用户在做数据分析就只加载数据处理相关的技能文件技能按需再开。这样模型看到的菜单短了选错的概率也低了。实现上注册表可以支持标签tag加载时按标签过滤。这比维护多个注册表实例简单。6.2 技能版本管理与灰度技能是会迭代的。今天read_file只支持 txt明天要支持 csv。直接改会影响到正在跑的流程。稳妥的做法是给技能加版本号新版本用新名字注册比如read_file_v2旧版本保留一段时间观察没问题再下线。这跟接口版本管理是一个思路。灰度则可以通过配置控制哪些用户走新技能。虽然听起来重但对于生产环境里的智能体这点投入是值得的。6.3 日志与可观测性技能体系跑起来之后最需要的是可观测性。每次调用要记录谁调的、调了什么技能、参数是什么、耗时多久、成功还是失败、返回了什么。这些日志在排查问题时是救命稻草。我一般会记录成结构化日志方便后续做统计。比如统计哪个技能调用最频繁、哪个技能失败率最高。失败率高的技能要么是描述有问题要么是执行逻辑有 bug都是优化点。6.4 安全边界哪些技能不能随便给最后说个严肃的话题。不是所有能力都适合封装成技能交给模型。涉及删除、转账、发送对外消息这类有不可逆副作用的操作一定要加人工确认环节。我的做法是给这类技能加一个requires_confirmation标记执行前先返回“即将执行 XX 操作请确认”等用户明确同意后再真正执行。另外技能的执行环境要隔离。读文件技能不应该能读到系统敏感目录网络请求技能要有域名白名单。这些边界在注册技能时就要设好别等出事再补。7. 我踩过的几个坑和一点心得说几个具体的。第一个坑是过度信任模型的参数填充。早期我没做校验结果模型把一个文件路径填成了path: C:\\Users\\...这种带转义的字符串程序直接报错。后来加了类型校验和路径规范化才稳定下来。教训是模型给的任何东西都要当成不可信输入。第二个坑是技能描述写得太“技术”。我一开始按 API 文档的风格写描述全是专业术语结果模型理解不了。后来改成大白话把“使用场景”放在最前面准确率立刻上去了。模型不是工程师它需要的是场景化的说明。第三个坑是返回值太大。有次一个查询技能返回了两万字的 JSON直接把上下文撑爆后续对话全乱了。后来强制所有技能返回值不超过 4000 字符超了就摘要问题解决。一点心得agent-skills 这套东西七分靠描述三分靠代码。代码逻辑其实很简单难的是怎么把技能“介绍”给模型让它用得对、用得准。所以别急着写执行函数先把描述打磨好把参数设计清楚后面会省很多事。这套体系搭好之后你会发现智能体能干的事一下子多了起来。从读文件、查数据到调接口、跑流程只要封装成技能模型就能调度。但记住能力越大边界越要划清楚。哪些能自动做哪些要确认哪些绝对不能碰心里得有本账。