agent-skills 实战：让大模型从会聊天到能干活

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", encoding="utf-8") as f: content = f.read() # 结果摘要：太长的内容截断 if len(content) > 4000: return {"content": content[:4000], "truncated": True, "note": "内容过长已截断，如需完整内容请分段读取"} return {"content": content, "truncated": False}

注册的时候，描述要写清楚：

registry.register( name="read_file", description="读取指定路径的文本文件内容。当用户需要查看某个文件里写了什么时使用。" "参数 path 是文件的完整路径，必须是字符串。" "返回文件内容，如果内容过长会被截断。" "如果文件不存在会返回错误，此时不要重试，直接告诉用户。", parameters={ "type": "object", "properties": { "path": {"type": "string", "description": "文件的完整路径"} }, "required": ["path"] }, handler=read_file_handler )

注意描述里那句“此时不要重试，直接告诉用户”。这句话是专门写给模型看的，能有效减少它拿到错误后反复重试同一个不存在文件的行为。这种“行为约束”写在描述里，比写在代码里管用。

4.4 主流程：把技能清单喂给模型

主流程要做的事，是把技能清单转成提示词的一部分，然后处理模型的调用请求。这里的关键是调用请求的解析要宽容。模型输出的格式可能不完全标准，比如多了一层引号、少了一个括号。解析时要做容错，能修就修，修不了再报错。

def build_system_prompt(registry): skills_json = json.dumps(registry.list_for_model(), ensure_ascii=False, indent=2) 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 参数总是填错或者漏填

参数问题的根源，九成在描述上。我整理了一个对照表，左边是常见错误，右边是修法。

这张表我贴在显示器边上，每次写新技能都对照一遍，能省下大量调试时间。

5.3 技能执行成功但模型理解错了结果

有时候技能明明返回了正确数据，模型却给出了错误结论。比如技能返回“库存 0”，模型却说“还有货”。这通常是返回值的结构不清晰导致的。模型看到一堆字段，不知道哪个是关键。

解决办法是让返回值自带语义。不要返回{"stock": 0}，而是返回{"stock": 0, "status": "缺货", "message": "该商品当前无库存"}。把结论直接写在返回值里，模型就不用猜了。这个技巧看起来笨，但极其有效。

5.4 多个技能冲突或者循环调用

当技能数量多起来，模型可能选错技能，或者在两个技能之间来回跳。比如先调search再调read再调search，陷入循环。防循环的手段有两个：一是设最大调用轮次，超过就强制结束并返回当前结果；二是在系统提示词里写明“同一个技能不要连续调用超过两次，如果两次都没拿到有用信息，直接告诉用户”。

技能冲突则要靠描述来区分。如果两个技能功能相近，一定要在描述里写清楚各自的适用场景和区别。比如search_web和search_local，描述里要明确一个是搜互联网、一个是搜本地库，别让模型自己猜。

5.5 排查速查表

注意：调试阶段一定要把模型的原始输出完整打日志，包括它生成的调用 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 这套东西，七分靠描述，三分靠代码。代码逻辑其实很简单，难的是怎么把技能“介绍”给模型，让它用得对、用得准。所以别急着写执行函数，先把描述打磨好，把参数设计清楚，后面会省很多事。

这套体系搭好之后，你会发现智能体能干的事一下子多了起来。从读文件、查数据，到调接口、跑流程，只要封装成技能，模型就能调度。但记住，能力越大，边界越要划清楚。哪些能自动做，哪些要确认，哪些绝对不能碰，心里得有本账。