1. 从agent-skills这个命名说起它到底指什么第一次看到agent-skills这个词很多人会下意识地把它理解成某个具体的库或者框架。但如果你在工程一线待过一段时间就会发现这类命名往往指向的是一类能力组织方式而不是某一个可以pip install的包。它描述的是一种思路把智能体agent需要具备的各种能力拆解成一个个独立、可复用、可组合的技能单元然后让智能体在运行时按需调用。这个思路其实并不新鲜。早在上世纪七十年代的专家系统里就有规则库的概念——把领域知识拆成一条条规则推理引擎负责匹配和触发。区别在于当年的规则是人工硬编码的而今天讨论的 agent-skills更多是在大模型具备通用推理能力之后重新思考哪些能力应该交给模型即兴发挥哪些能力应该固化成可调用的技能。我个人的判断是agent-skills 的核心价值不在于让智能体更聪明而在于让智能体的行为更可控、更可维护。一个纯靠提示词驱动的智能体你很难预测它在边界情况下会做什么而一旦把关键能力封装成技能你就有了明确的接口、明确的输入输出、明确的失败模式。这对生产环境来说是质的差别。这篇文章适合三类人看一是正在做智能体应用、被提示词越写越长、行为越来越飘困扰的开发者二是想理解智能体工程化落地思路的技术负责人三是对 AI 应用架构感兴趣、想搞清楚技能这个概念到底怎么落地的人。我会从概念拆解讲到目录结构、从技能设计讲到调度策略尽量把每个为什么都讲透。2. 技能单元的边界怎么划拆得太细和太粗都是坑2.1 一个技能应该管多宽这是设计 agent-skills 时第一个要回答的问题也是最容易翻车的地方。我见过两种极端一种是把技能拆得极细比如读取文件是一个技能、解析 JSON是一个技能、提取字段又是一个技能结果一个简单任务要串七八个技能调度开销比实际干活还大另一种是拆得太粗一个技能叫处理用户请求里面塞了几百行逻辑本质上又退化成了一个黑盒。我的经验法则是一个技能应该对应一个语义上完整、可独立测试、有明确成功判据的操作。判断标准很简单——你能不能给这个技能写一个单元测试输入固定、输出可断言如果能说明边界清晰如果测试里要 mock 一大堆外部状态说明它耦合太重该拆。举个具体例子。假设你在做一个文档处理智能体需要从一堆 PDF 里提取结构化信息。提取 PDF 文本是一个合理的技能因为它输入是文件路径、输出是纯文本可测试。从文本里抽取合同金额也是一个合理技能输入文本、输出金额字段。但处理合同就不是一个好技能因为它太宽泛成功判据模糊。2.2 技能与工具tool的区别在哪很多人会把 agent-skills 和 function calling 里的 tool 混为一谈。它们确实有重叠但侧重点不同。Tool 更偏向原子操作——调一个 API、查一次数据库、发一封邮件。而 skill 更偏向完成一件事的完整流程它内部可能调用多个 tool也可能包含决策逻辑。打个比方tool 像是厨房里的刀、锅、铲skill 像是炒一盘蛋炒饭这道菜的做法。你可以只用工具即兴发挥但如果你要保证每次炒出来的味道稳定就需要把做法固化下来。Agent-skills 要解决的就是这个稳定复现的问题。注意不是所有能力都值得封装成技能。那些一次性的、极少复用的、或者高度依赖上下文的操作留在提示词里让模型即兴处理反而更灵活。技能化的成本不低别为了架构好看而过度设计。2.3 技能清单的维护成本技能一旦多起来清单本身就成了负担。我建议在项目早期就建立一份技能注册表至少包含这几个字段技能名、功能描述、输入 schema、输出 schema、依赖的外部资源、失败时的降级策略。这份表不用多复杂一个 Markdown 表格或者一个 YAML 文件就够但一定要有而且要随代码同步更新。我踩过的坑是早期图省事技能描述直接写在代码注释里结果三个月后技能加到二十多个谁也说不清哪个技能还在用、哪个已经废弃。后来不得不花两天时间做了一次全面梳理。这个教训很直接——技能注册表不是文档负担是调度器的输入。很多调度策略比如根据任务描述匹配最合适的技能直接依赖这份表的质量。3. 目录结构与技能描述文件的设计3.1 为什么目录结构值得单独拿出来讲在 agent-skills 这类项目里目录结构不只是代码放哪的问题它直接决定了技能能不能被自动发现、能不能被独立加载、能不能被单独测试。一个设计良好的结构能让新增技能变成复制一个文件夹、改几个字段的机械操作一个糟糕的结构会让每次加技能都像在拆炸弹。我推荐的结构大致是这样agent-skills/ skills/ extract_pdf_text/ skill.yaml handler.py test_handler.py extract_contract_amount/ skill.yaml handler.py test_handler.py registry.py dispatcher.py config/ settings.yaml每个技能一个独立目录目录名就是技能标识。skill.yaml描述元信息handler.py是实际逻辑test_handler.py是单元测试。这种一个技能一个包的做法好处是技能之间零耦合删掉一个目录不会影响其他技能。3.2 skill.yaml 里该写什么这个描述文件是整个技能体系的核心。我一般会包含以下字段字段作用是否必填name技能唯一标识建议用下划线命名是description一句话说明这个技能干什么调度器会读它是inputs输入参数 schema含类型和是否必填是outputs输出结构 schema是timeout超时时间秒否默认 30retry失败重试次数否默认 0fallback失败时的降级技能名否description这个字段特别关键。如果你打算用模型来做技能匹配后面会讲这段描述的质量直接决定匹配准确率。写的时候要站在调度器视角——它需要知道什么信息才能判断该不该选这个技能。比如从 PDF 文件提取纯文本内容适用于文本型 PDF不适用于扫描件就比处理 PDF有用得多。3.3 handler 的接口约定handler 的接口设计要遵循一个原则输入输出都是纯数据不依赖全局状态。我通常约定 handler 接收一个字典、返回一个字典异常统一抛出。这样做的原因是纯函数式的接口最容易测试、最容易并行、最容易在不同运行环境里迁移。def handle(inputs: dict) - dict: file_path inputs[file_path] # ... 实际逻辑 return {text: extracted_text, page_count: n}不要在这个函数里读环境变量、不要连数据库、不要写日志到特定路径。这些副作用应该由外层框架统一处理。handler 越干净技能就越可复用。4. 技能调度让智能体知道什么时候该用哪个技能4.1 三种调度策略的取舍技能有了接下来就是怎么选。我实践下来主要有三种策略各有适用场景。第一种是显式指定。调用方直接说用 extract_pdf_text 这个技能调度器不做任何判断。这种方式最可控适合流程固定的场景比如一条已经编排好的流水线。缺点是灵活性差新增场景要改调用代码。第二种是规则匹配。根据输入的关键词、文件类型、任务标签等硬性条件来选技能。比如输入是.pdf就走 PDF 相关技能。这种方式快、可预测但规则一多就难维护而且覆盖不了模糊场景。第三种是模型匹配。把所有技能的 description 拼成一段文本让模型根据当前任务描述选出最合适的技能。这种方式最灵活能处理用户说了句人话需要判断意图的场景。缺点是慢、有不确定性、需要处理选错的情况。我的建议是混合使用主流程用显式指定保证稳定入口处用模型匹配做意图识别中间用规则匹配做快速分流。不要指望一种策略打天下。4.2 模型匹配的提示词怎么写如果决定用模型做技能匹配提示词的设计有几个要点。首先技能列表要结构化呈现每个技能给出名称和描述不要只给名称。其次要明确告诉模型如果都不合适返回 none否则它会在没有合适技能时硬选一个。第三要求模型输出结构化的结果比如 JSON方便程序解析。一个可用的模板大致是你是一个技能调度器。根据用户任务从下列技能中选出最合适的一个。 可用技能 - extract_pdf_text: 从文本型 PDF 提取纯文本 - extract_contract_amount: 从合同文本中抽取金额字段 - summarize_text: 对长文本生成摘要 用户任务{task} 请只返回 JSON{skill: 技能名或 none, reason: 简短理由}实测下来加上reason字段能显著提升匹配质量因为模型在解释理由的过程中会更认真地做判断。这个技巧在很多分类任务里都管用。4.3 匹配失败与降级再好的匹配也会出错。所以调度层必须处理三种失败没匹配到技能、匹配到了但执行失败、匹配到了多个候选。没匹配到时不要直接报错给用户而是回退到通用对话模式让模型用自然语言回应同时记录这次未匹配的任务作为后续新增技能的依据。执行失败时看技能有没有配置 fallback有就走降级没有就返回明确的错误信息。多个候选时可以按优先级排序或者让模型再选一次。提示把每次调度决策任务、选中技能、是否成功都记下来积累一段时间后你会发现真正高频使用的技能可能就那么几个而有些技能几乎没被触发过。这份数据是优化技能清单最直接的依据。5. 技能内部的错误处理与可观测性5.1 错误分类比错误处理更重要技能执行失败时最忌讳的就是笼统地抛一个执行失败。我习惯把错误分成三类输入错误参数缺失、格式不对、环境错误依赖服务不可用、文件不存在、逻辑错误代码 bug、边界没处理。这三类的处理方式完全不同——输入错误应该快速失败并提示调用方环境错误可以重试逻辑错误必须修代码。在 handler 里我通常用自定义异常来区分class SkillInputError(Exception): pass class SkillEnvError(Exception): pass class SkillLogicError(Exception): pass调度器捕获不同类型的异常走不同的分支。这样做的价值在于当系统跑了一段时间后你能从错误分布里看出问题所在——如果大量是输入错误说明上游调用方有问题如果大量是环境错误说明依赖不稳定。5.2 日志该记什么技能执行的日志我建议至少记这几项技能名、输入参数的摘要注意脱敏、执行耗时、结果状态、错误类型。不要记完整输入输出一是体积大二是可能含敏感信息。摘要可以只记关键字段比如文件路径只记文件名和大小。耗时这个指标特别有用。技能执行时间突然变长往往预示着依赖服务变慢或者数据量增长。我一般会设一个阈值超过就告警。这个阈值不用很精确凭经验给个值跑一段时间再调整。5.3 让技能可观测的轻量做法不一定要上完整的链路追踪系统。对于中小规模的项目一个简单的做法是每次技能调用生成一个 trace_id把相关日志都打上这个 id出问题时按 id 一搜就能还原整个调用链。这个做法成本极低但排查效率提升明显。另外建议给每个技能加一个健康检查入口用一组固定的输入跑一遍看输出是否符合预期。这个检查可以定时跑也可以在上线前跑。它能在依赖服务悄悄变化时第一时间发现问题。6. 从零搭一个最小可用版本的完整步骤6.1 环境准备与依赖选择先把最小闭环跑起来别一上来就追求大而全。我建议的起步依赖很简单一个 YAML 解析库、一个模型调用 SDK如果要用模型匹配、一个测试框架。其他的等真正需要了再加。Python 环境下pyyaml处理描述文件pytest做测试模型调用按你实际用的服务选对应 SDK。不要引入重量级框架agent-skills 这类东西框架越轻越好因为它的核心价值在于结构清晰而不是功能丰富。6.2 实现技能加载器加载器的职责是扫描skills/目录读取每个skill.yaml把 handler 动态导入进来形成一个内存中的技能表。核心逻辑大概是这样import os, yaml, importlib.util def load_skills(base_dirskills): skills {} for name in os.listdir(base_dir): skill_dir os.path.join(base_dir, name) meta_path os.path.join(skill_dir, skill.yaml) if not os.path.isfile(meta_path): continue with open(meta_path, encodingutf-8) as f: meta yaml.safe_load(f) handler_path os.path.join(skill_dir, handler.py) spec importlib.util.spec_from_file_location(f{name}_handler, handler_path) module importlib.util.module_from_spec(spec) spec.loader.exec_module(module) skills[name] {meta: meta, handler: module.handle} return skills这段代码不复杂但有几个细节要注意一是编码统一用 utf-8否则中文描述会乱码二是动态导入时模块名要唯一避免冲突三是加载失败要能跳过并记录不能让一个坏技能拖垮整个加载过程。6.3 实现调度器调度器接收任务描述返回选中的技能并执行。最小版本可以先用规则匹配等跑通了再换成模型匹配。核心逻辑是遍历技能表根据 meta 里的 description 和输入特征做匹配选中后调用 handler处理异常返回结果。def dispatch(task, inputs, skills): # 简化版按关键词匹配 for name, item in skills.items(): if any(kw in task for kw in item[meta].get(keywords, [])): try: return {skill: name, result: item[handler](inputs)} except Exception as e: return {skill: name, error: str(e)} return {skill: None, error: no matching skill}这个版本很粗糙但它能让你快速验证整个链路是否通畅。跑通之后再把匹配逻辑换成模型匹配把错误处理细化把日志加上。6.4 写第一个技能并测试拿提取文本文件行数这种最简单的技能练手。skill.yaml里写清楚 name、description、inputs、outputshandler.py里实现读取文件、统计行数、返回结果。然后写测试覆盖正常文件、空文件、不存在的文件三种情况。这一步的意义不在于技能本身而在于验证你的目录结构、加载器、调度器、测试流程是否都正常工作。第一个技能跑通了后面加技能就是复制粘贴改字段的事。7. 实测中容易踩的几个坑7.1 技能描述写得太技术模型匹配不准我一开始写 description 的时候习惯用技术语言比如基于正则表达式解析文本。结果模型匹配经常选错因为它不理解正则表达式和用户任务的关系。后来改成从文本中提取符合特定格式的字段比如日期、金额、编号匹配准确率明显提升。这个坑的本质是description 的读者是调度器可能是模型不是人类开发者。要站在理解任务意图的角度写而不是描述实现方式的角度写。7.2 技能之间隐式依赖导致单独测试失败有个技能在 handler 里偷偷读了一个全局配置单独跑测试时配置没加载直接报错。这种隐式依赖非常隐蔽因为集成测试时一切正常只有单独测试才暴露。解决办法就是前面说的——handler 保持纯函数所有依赖通过参数传入。7.3 超时设置不合理长任务被误杀默认超时设了 30 秒结果有个处理大文件的技能经常跑到 40 秒被调度器判定超时。后来给这类技能单独配置了更长的超时。教训是超时时间应该按技能特性配置而不是全局一刀切。在 skill.yaml 里留一个 timeout 字段需要时覆盖默认值。7.4 技能版本升级导致调用方不兼容改了某个技能的输入参数名结果所有调用它的地方都挂了。这个坑的预防办法是技能接口一旦发布尽量只增不改确实要改就新增一个技能名老技能保留一段时间做过渡。接口兼容性这件事在技能体系里和在 API 设计里一样重要。8. 技能体系后续可以怎么演进跑通最小版本之后有几个方向值得继续投入。一是技能组合把多个技能编排成一条流水线用一个复合技能对外暴露这样调用方不用关心内部细节。二是技能缓存对于输入相同、结果确定的技能缓存结果能显著降低开销。三是技能市场把通用技能抽出来做成可共享的包不同项目直接引用。我个人最看好的方向是技能的可观测性建设。当技能数量上到几十个之后哪个技能在什么场景下表现如何这个问题会变得越来越重要。把调度决策、执行结果、耗时、错误都结构化记录下来用数据驱动技能清单的优化这比拍脑袋增删技能靠谱得多。另外提醒一句不要为了技能化而技能化。有些逻辑就是一次性的写死在流程里反而更简单。技能体系的价值在于复用和可控如果一个能力只用一次、也不会出问题那它不值得被封装成技能。这个判断标准我在多个项目里反复验证过基本没出过错。