构建Agent技能库：让大模型从自由发挥走向稳定执行

做Agent开发这些年，我最深的感受是：模型的聪明程度，很多时候不取决于模型本身，而取决于你给它准备的“工具箱”整不整齐。这个工具箱，就是agent-skills。

我第一次意识到这个问题，是在一个文档处理需求上。模型能看懂PDF里的表格，但让它自己逐页解析文件、提取文本、组织章节，它就会开始“自由发挥”，输出格式一天一个样，今天给纯文本，明天给JSON，后天可能就是一段带Markdown的混合体。后来我把解析、提取、转换这些固定动作全部固化成了标准技能，模型只负责判断“当前该调哪个技能、参数是什么”，整个流程才稳定下来。

如果你也在做Agent相关的应用开发，或者正在为“模型执行任务不稳定”发愁，这篇文章值得看完。我不会讲那些悬空的概念，而是直接拆解agent-skills这套方案的核心设计、实现细节、工程化管理和踩坑经验，尽量做到你可以照着搭一套自己的技能库。

1. Agent Skills到底解决什么问题

1.1 从“提示词指挥”到“技能调用”

先问一个问题：你在让模型干一件具体事情的时候，是希望它“自由发挥”，还是希望它“照着标准流程做”？

对于复杂任务，答案是后者。

所谓Agent Skills，就是把完成某一类任务的处理能力固化成标准模块。每个技能都有明确的输入参数、执行逻辑和输出格式。Agent运行时，大模型只做两件事：判断当前任务应该用哪个技能，然后根据用户需求生成符合规范的参数。至于技能内部怎么实现，模型完全不关心。

这样做的好处很明显。提示词里的“你是一个文档处理助手”这种话，本质上是让模型自己想象一套处理流程，结果不可控。而技能调用相当于把流程写成了代码，模型只需要做“决策”和“翻译”，不需要“发明”。

我举个例子。让模型处理一份 Excel 报表，如果你在提示词里说“请清洗这份数据”，模型可能会尝试写Python代码，写出来的代码还未必能跑。但如果你的Agent技能库里有一个 spreadsheet_cleaner 技能，模型就会把自己的工作简化为：调这个技能，传文件路径和清洗规则参数。能不能跑是技能层保证的，而不是模型临场发挥的。

这个思路的核心价值，是把“模型的能力”和“系统的能力”分开了。模型的职责是理解需求和做决策，系统的职责是稳定执行。两者通过技能层对接，而不是靠一段越来越长的提示词硬撑。

1.2 技能、工具、插件的边界在哪

很多人分不清技能和工具、插件的区别。我在实际开发中会把这三者区分得很清楚：

工具（Tool）是最小粒度的功能单元，比如“发送HTTP请求”“读取文件”“执行Shell命令”。插件（Plugin）通常是外部系统的接入适配器，比如对接某个IM平台的接口。而技能是面向完整任务场景的“组合拳”，它可以从一个工具或脚本开始，慢慢长成一套完整的处理能力。

用生活化的话说：工具是螺丝刀，插件是电动螺丝刀套装，技能则是“你能清楚地告诉别人‘我擅长修某类电器’的能力描述+对应的维修流程”。

这也是agent-skills项目名字里的核心含义，它强调的不是某个工具，而是Agent可以主动检索、选择、组合的一组“技能包”。比如你有一个“文档解析”技能，又有一个“要点提炼”技能，Agent面对一份合同，就知道先调文档解析，拿到文本后再调要点提炼，整个链路是模型自主编排的，但每一步执行的可靠性由技能层兜底。

有些人会把技能库做成“提示词模板库”，觉得一个技能就是一个System Prompt。这里我要提醒一句：提示词模板只能影响模型的输出风格，无法保证执行结果真实可靠。真正的技能必须包含可执行的代码实现，提示词描述只是给模型看的“使用说明书”，不是技能本身。

2. 一个技能模块的核心组成与设计思路

2.1 描述文件：给模型看的说明书

一个技能需要让模型“看得懂、选得准、用得对”，关键就在描述文件。这个文件决定了模型在什么场景下会想起这个技能，以及它能不能正确填报参数。

我见过很多失败案例，描述文件写得像产品PR稿：“这是一个功能强大的文档处理技能，能够高效处理多种常见文档格式。”这种描述在模型眼里就是废话。模型需要知道的是：这个技能解决什么问题，什么场景必须调它，什么场景不应该调它，以及调用时每个参数到底填什么。

一份合格的技能描述，至少要包含以下几块：

写description有个很实用的技巧：把“反例”写进去。比如你做一个PDF转Markdown的技能，description里明确写“如果用户只想了解PDF的大致主题，不需要完整内容，请勿调用此技能，改用摘要技能”。这条反例看着不起眼，实际能大幅降低模型的乱调用概率。

2.2 参数约束：把模型的创造力关进笼子里

模型有个特点：给它自由，它就发挥。给它约束，它反而更可靠。参数层是最需要严格约束的地方。

我在agent-skills里统一用JSON Schema定义参数。以文档抽取技能为例：

{ "type": "object", "required": ["source_path"], "properties": { "source_path": { "type": "string", "description": "要解析的PDF文件绝对路径" }, "output_format": { "type": "string", "enum": ["markdown", "plaintext", "json"], "default": "markdown", "description": "输出格式" }, "page_range": { "type": "array", "items": {"type": "integer"}, "description": "可选，限定页码范围，例如[1, 3]" } } }

为什么参数层要这么严？因为模型本质是概率模型，参数名稍微模糊一点，它就可能填错。比如你把参数定义成 path 而不是 source_path，模型可能传进去一个URL，也可能是相对路径。加了JSON Schema，你就有了三层防线：运行前由框架校验类型、运行时由实现层二次校验、返回结果时由模型自行判断是否合理。

一个常见的参数问题是枚举值。定义 output_format 时用 enum 限定，模型就不会给你传一个 “markdown文档” 这种自然语言值。如果某个参数允许动态组合，那就别用enum，而是在description中明确格式模板，比如“格式为 YYYY-MM-DD”。模板比枚举更灵活，也给了模型准确的参考。

2.3 返回结构：让模型能顺利“接住”结果

技能执行完后，返回值不是给人类看的，是给模型看的。很多人在这一步栽跟头：技能执行成功了，但返回的是一个巨大的文本块，模型直接“吞”不下去，导致后续生成的结果质量很差。

我在agent-skills中约定所有技能统一返回结构化格式，核心字段如下：

{ "success": true, "data": { "excerpt": "前500字的内容摘要", "page_count": 12, "output_path": "/tmp/xxx.md" }, "error": null, "latency_ms": 1200 }

注意，我没有让技能把几万字全文全部塞进返回体。data里放的是模型需要的“决策信息”：执行结果、关键统计、输出文件路径。模型看到这些信息后，如果需要全文，它会根据output_path自己去下一步处理；如果只是要总结，那excerpt就够了。

这里有个容易被忽略的点：给模型返回超长内容，既浪费token，又让模型“迷失重点”。技能实现层应该做好内容裁剪和分层摘要，把原始全量内容落到磁盘文件，返回时只给精简版。这套思路我屡试不爽，尤其是处理PDF、Word这类大文档时，效果非常明显。

3. 实操：从零构建一个可复用的文档处理技能

3.1 场景拆解：什么任务适合做成技能

不是所有任务都适合做成技能。我判断是否技能化，就看三条标准：

第一，任务有明确的输入输出边界。比如“把PDF转成Markdown”有边界；“帮用户写一篇营销文案”没有边界。

第二，任务需要稳定的确定性执行。涉及文件解析、数据清洗、格式转换这类操作，让模型临场写代码太不可控，必须技能化。

第三，任务会被重复调用。哪怕一周只用几次，只要它是稳定的高频路径，就值得沉淀成技能。

基于这三条，我选了一个最常见不过的场景：批量解析PDF报告，生成结构化文本。这个场景适合演示，因为大部分开发者都遇到过类似需求。

3.2 技能实现与注册：一份可以直接改着用的模板

完整技能包含两个部分：描述文件和实现代码。目录结构如下：

skills/ extract_pdf_to_markdown/ skill.yaml impl/ main.py requirements.txt tests/ test_basic.py sample_input.pdf

skill.yaml对应前面说的描述文件，impl/main.py是实际执行逻辑。我写一个最小实现，你可以直接抄走改：

--- name: extract_pdf_to_markdown description: 将PDF文件抽取为Markdown格式的纯文本。当用户需要读取PDF文档内容、提取表格或批量整理报告时使用。如果用户只想了解文档主题或生成摘要，不要调用本技能，建议使用摘要技能。 version: 1.0.0 parameters: type: object required: ["source_path"] properties: source_path: type: string description: "需要解析的PDF文件绝对路径" keep_layout: type: boolean description: "是否尽量保留原始排版格式，默认false" default: false return: type: object properties: output_path: type: string description: "生成的Markdown文件路径" page_count: type: integer description: "PDF总页数" excerpt: type: string description: "前500字内容摘要"

实现代码用Python写，示意如下（解析库部分按你的实际环境替换）：

import json, sys, os # 示意：任何你选定的PDF解析库都可以 # from pdf_extract import load_pdf def run(source_path: str, keep_layout: bool = False): if not os.path.exists(source_path): return {"success": False, "error": "file_not_found"} # text, page_count = load_pdf(source_path, layout=keep_layout) # 这里我用占位数据演示返回结构，实操时替换为真实解析逻辑 text = "替换为真实解析出的PDF文本内容。" page_count = 12 os.makedirs("/tmp/skill_outputs", exist_ok=True) output_name = os.path.splitext(os.path.basename(source_path))[0] + ".md" output_path = os.path.join("/tmp/skill_outputs", output_name) with open(output_path, "w", encoding="utf-8") as f: f.write(text) return { "success": True, "data": { "output_path": output_path, "page_count": page_count, "excerpt": text[:500] } } if __name__ == "__main__": args = json.loads(sys.argv[1]) result = run( source_path=args.get("source_path"), keep_layout=args.get("keep_layout", False) ) print(json.dumps(result, ensure_ascii=False))

这个模板里有几个设计细节值得说明：

一是入口统一用JSON字符串参数+标准输出返回。这样无论Agent运行时是用命令行调用、还是用子进程加载，都可以用同一套协议对接。

二是临时输出统一放到 /tmp/skill_outputs 这种隔离目录，不污染项目工作区。

三是返回结构严格遵循前面约定的 {success, data, error} 格式。不管技能内部发生什么，都要转成这个结构，绝不要让Python抛异常直接炸出去。

注册环节很简单：把skill.yaml和impl目录放在agent-skills根目录下，运行时启动时扫描并加载所有技能描述，构建索引。实现上就是一个遍历目录+读取yaml的过程，不用写复杂逻辑。

3.3 验证：别急着接模型，先测技能本身

很多人把技能写完就接Agent，结果出问题时说不清是模型的问题还是技能的问题。我的习惯是：三层验证，逐层放行。

第一层是直接调用。拿一个真实的PDF文件，执行 python main.py '{"source_path": "sample.pdf"}'，看返回的JSON是否正常，输出的Markdown是否完整。这层过了，才说明技能实现本身没问题。

第二层是脱离模型做“模拟Agent调用”。写一段测试脚本，模拟模型可能传的各种参数组合，包括合法参数、缺参、错误类型、不存在的路径。这一步是为了确认技能在异常输入下不会崩溃，而是返回结构化错误。

第三层才接入真实模型。跑一个最小对话：让模型执行“把sample.pdf转成Markdown”。观察它选技能是否正确、参数填得是否正确、拿到返回后能不能继续处理。

很多人觉得第三层就是全部了，其实前两层才是兜底。如果第一层就挂了，后面排查会非常痛苦，因为你得同时调试模型和代码。

4. 技能库的工程化：从“能跑”到“能长期维护”

4.1 目录结构与命名规范

技能一多，就会遇到管理问题。最典型的就是命名混乱：有的技能叫“提取PDF”，有的叫“pdf2md”，还有的叫“文档解析_v3”。模型面对一堆命名风格迥异的技能，调用准确率必然下降。

我定的命名规范很简单：

• 技能名统一用 动词_对象 的格式，比如 extract_pdf_text、generate_chart、clean_csv。
• 参数名统一小写蛇形，比如 source_path、output_dir。
• 每个技能目录内必须有skill.yaml和impl，缺一不可。
• 技能版本号用语义化版本，1.x表示稳定，0.x表示试验阶段。

命名规范影响的是“可发现性”。Agent在技能库中做选择时，靠的是embedding匹配和描述理解。名字取得越直白，匹配越准。别玩文艺，别用缩写，直接表达用途就好。

4.2 测试与版本管理

技能是会腐烂的。底层依赖升级、文件格式变化、模型理解方式变化，都可能导致某个技能悄悄失效。没有测试体系，你就只能靠用户报障来发现问题。

我会在每个技能目录下放一个tests目录，包含三类测试：

用不到很重的测试框架，pytest就够。关键是定期跑回归，尤其是每次升级大模型版本时，跑一遍全部技能的契约测试，能提前发现模型对参数理解的偏差。

版本管理上，我建议技能描述文件的version和大模型对这个技能的“熟悉程度”联动。如果换了模型版本后调用成功率下降，说明这个技能的描述对新模型不够友好，需要调整description，然后升版本。

4.3 复用策略：组合技能而不是堆叠技能

技能库壮大后，一个重要误区是：把任务拆得太碎，然后让模型自己“编排一切”。模型编排能力是有限的，面对一个20步的任务链路，每步出错率哪怕只有2%，整体成功率也会掉到约66%。这时候必须做“组合技能”。

组合技能不是简单地把几个技能代码拼在一起，而是面向一个更上层的任务重新封装。比如我有 extract_pdf_to_markdown 和 summarize_text 两个基础技能，那么我可以做一个 report_analyzer 组合技能，内部先调PDF解析，再自动提炼核心要点，最终直接输出一份结构化报告摘要。模型只需要调用一个技能，拿到完整结果。

这样做的核心原因在于：模型调用的节点越少，出错概率越低。你要把“模型要做的事”降到最低，把“技能要做的事”提得更高。一个设计优秀的组合技能，往往比让模型自由编排十几个底层小技能更稳定，也更省token。

这也意味着，技能库不是越大越好，也不是越细越好。技能的粒度要跟任务复杂度和模型能力匹配。模型能力强，可以适当保留小粒度技能；模型能力一般，尽量提供“一体成型”的大技能。

5. 真实踩坑：技能失效的常见原因与排查思路

5.1 模型不调用或乱调用技能

最让人头疼的问题就是：该调的时候不调，不该调的时候乱调。

“该调不调”通常是因为description里的触发条件太隐晦。比如PDF解析技能的description写“提取PDF内容”，但用户说的是“把这份合同读一下，告诉我违约金条款”，模型可能觉得这不叫“提取PDF”，于是自己硬读，结果读不出来。解决方法是把description写成更口语化的触发条件，覆盖多种表达方式：“当用户希望读取、查看、解析PDF文档内容时使用本技能。”

“不该调乱调”则常常是反例没写。模型看到有PDF技能，用户问怎么做一个PDF合并，它也去调这个技能。最后发现技能不支持合并，整个链路中断。经验之谈：description里一定要有“禁止场景”清单。

5.2 参数幻觉与运行时校验

参数幻觉是Agent开发的专属坑。模型明明没有拿到文件路径，却会“编造”一个长得像路径的参数，比如 /Users/admin/Desktop/报告.pdf，然后技能执行时果断报错。

对策分两层。第一层是约束：在参数schema里用description强制说明“source_path必须来自用户消息或历史工具返回，不得自行构造”。第二层是兜底：技能实现层在读取文件前，检查路径是否存在，不存在直接返回错误描述，而不是抛一堆堆栈。这样即便模型填了假路径，Agent也能看到友好提示，自己修正对话策略。

我还要提醒：技能执行层用的所有临时目录都要在技能启动时重建一遍。模型可能会传一个已经失效的临时文件路径，如果目录被清理过，就会出现“参数存在但文件没了”的诡异bug。

5.3 超时、异步与长任务处理

技能执行时间过长，也是个高频问题。大模型调用技能的同步等待时间通常有限，如果技能要跑一两分钟，模型那边可能先超时断开。处理方案是给技能加“异步任务”模式：技能接收任务后立即返回 task_id，随后在后台执行，模型可以用轮询任务状态的技能查询进度。

异步模式会让技能设计复杂不少，所以我的建议是：优先压缩技能执行时间，比如解析大文件时只抽前几十页，而不是全量处理。让模型按需“增量调用”更简单可靠。只有当技能确实无法快速完成时，再考虑异步改造。

5.4 排查流程：从日志里找模型的“决策痕迹”

出了故障先别慌，按下面这个流程来：

第一步，查原始请求。看用户到底说了什么，模型当时拿到哪些上下文。这一步排掉“用户需求就没说清楚”的情况。

第二步，查模型调用的技能名和参数。框架层必须有日志记录这些信息。没有日志，排查就是盲人摸象。

第三步，直接跑技能。用相同参数引手动执行，看是不是技能实现的问题。

第四步，查返回结果。看模型拿到技能返回值后，后续生成有没有合理利用这些信息。

排查到后来你会发现，绝大多数技能失效问题，根子不在代码，而在“描述文件与模型理解之间的错位”。代码挂了你能立刻看到，描述错位却要花很长时间才能定位。所以我在开发agent-skills时，养成了一个习惯：每个技能的描述文件都当作核心代码来review，而不是当成可有可无的文档。

写到最后补一个我自己坚持到现在的做法：每新增一个技能，都强迫自己写一条“反例”进描述文件。比如文档抽取技能，我会写清楚“如果只是想获得摘要，不要调本技能，请使用摘要技能”。这条反例至少帮我省掉了一半的错误调用排查时间。你别嫌写反例麻烦，模型真的会踩你懒得写反例时踩过的每一条坑。