做AI Agent这半年多我最大的感受不是模型不够聪明也不是编排框架不好用而是能力散落一地。今天要聊的是我一直在维护的一个叫 agent-skills 的技能库项目核心就三件事怎么把Agent需要用到的能力封装成标准化的“技能”怎么让模型在合适的时机自动选对技能以及怎么让这些技能跨项目复用。如果你和我一样被工具列表冗长、提示词越写越长、模型乱调工具这些问题困扰这篇文章应该能给你一些可以直接落地的方案。1. 为什么Agent需要一套“技能”机制1.1 从“提示词堆砌”到“技能复用”我最早做的Agent很简单系统提示词里塞几十个工具的JSON Schema然后让模型自己决定调用哪一个。结果大家应该都猜得到——工具一多模型就开始犯迷糊。它经常把参数填错甚至明明有搜索工具不去用非要凭记忆编一个答案出来。后来我意识到一个问题Agent的能力本质上是“模型上下文可执行单元”但大多数人只关注前两者对“可执行单元”的组织方式非常随意。工具函数有了说明文档没有说明文档写了依赖又没管某个Agent调得好好的技能换一个项目又要重新写一遍。这些痛点让我下定决心做一套自己的技能库名字就叫 agent-skills。技能机制和普通工具最大的区别在于工具解决的是“能做什么”技能解决的是“什么时候做、怎么做、做完了怎么验证”。一个技能包里除了可执行的代码还有模型需要理解的触发条件、参数合约、使用限制、依赖环境和测试用例。它更像一个完整的“岗位说明书”而不是一个孤零零的函数签名。1.2 技能与工具的核心差异为了把这个概念说清楚我整理过一个对比表维度普通工具 Tool技能 Skill内容函数名参数签名SKILL.md 入口脚本 依赖 测试触发方式模型根据函数名猜测模型根据描述中的触发条件决策使用限制没有或很少明确写出禁忌场景和边界依赖管理项目级全局依赖技能自带依赖清单可按需隔离复用性需要重新注册目录拷贝即可跨项目复用可验证性基本靠人工内置测试夹具可离线验证我当时决定用“目录即技能”的设计思路每个技能占用独立目录目录里必须有SKILL.md入口描述其余文件按需放置。这样整个仓库看起来极其规整加载器也能通过扫描目录自动发现技能不需要每次手动注册。这个设计还有一个隐藏好处团队协作时谁要新增一个能力只要开一个目录建一个SKILL.md就能提交不用去动核心代码。技能和主程序之间的耦合被降低了Agent的扩展从“改代码”变成了“加配置”。2. 技能仓库的整体设计2.1 目录结构让“技能包”一眼看懂仓库结构我一直沿用下面这套没什么花哨的胜在清晰agent-skills/ ├── skills/ │ ├── web-search/ │ │ ├── SKILL.md │ │ ├── search.py │ │ ├── requirements.txt │ │ └── tests/ │ │ ├── fixtures.json │ │ └── test_search.py │ ├── pdf-summary/ │ │ ├── SKILL.md │ │ ├── summarize.py │ │ ├── templates/ │ │ └── requirements.txt │ └── schedule-helper/ │ ├── SKILL.md │ └── calendar_utils.py ├── loader/ │ ├── skills_loader.py │ └── action_table.json └── examples/ └── quickstart.py这套结构里skills/下面每个子目录就是一个独立技能。命名统一用小写加中划线和Python模块名保持一致避免大小写问题。入口文件我习惯叫run.py或者直接根据功能命名比如search.py只要在SKILL.md里写清楚即可。你可能会问为什么不直接在代码库里建一个大的tools/包而是要用目录隔离因为技能是给模型“看”的东西模型不看代码只看SKILL.md。目录隔离之后加载器可以单独读取元信息也可以在后续做权限控制时按技能维度配置权限灵活性高很多。2.2 SKILL.md让模型“读懂”技能的关键整个设计里最核心的文件就是SKILL.md。它相当于是技能的“说明书”模型通过读它来决定是否调用、如何调用。我早期失败的原因之一就是说明书写得像接口文档后来参考了一些主流技能格式后总结出一套好用的模板。以web-search技能为例SKILL.md是这样的--- name: web-search description: - 当用户需要获取最新资讯、查询实时信息、搜索网页内容时使用此技能。 支持关键词搜索、指定站点限制、控制返回条数。 注意知识性问答和历史事件请直接回答不需要使用本技能。 version: 1.3.0 tags: [search, web, tool] parameters: type: object properties: query: type: string description: 搜索词建议控制在30字以内 examples: [为什么今年桂花不开] domain: type: string description: 可选站点限制例如 example.com default: count: type: integer default: 5 minimum: 1 maximum: 20 required: [query] --- 实现说明入口文件为 search.py调用方式为 python search.py --query 关键词 --count 5。 返回 JSON 数组数组元素包含 title、url、snippet 三个字段。我来说说每个字段为什么重要description这是整个技能被正确触发的关键。第一句话必须写明“什么时候用”第二句话写“能提供什么”最后要写“什么时候别用”。负向描述特别有用能显著减少误调用。parameters必须用JSON Schema格式别自定义格式。模型对JSON Schema的训练数据足够多识别准确率高。而且后续可以直接复用校验库做参数检查。version技能的迭代要有版本号。很多技能在Agent里跑得好好的某天你改了输入输出格式没注意版本模型仍然按老格式传参当场翻车。有了版本号至少能追踪问题。tags不是给模型看的是给加载器做分组和筛选用的。比如按“搜索类”“文档类”“日常工具类”分组在Agent侧可以按需加载。SKILL.md的正文部分我建议写得简短但明确入口文件是什么、调用方式是什么、返回结构长什么样。这里不是给模型看的——模型只看frontmatter就够了——而是给维护者和其他开发者看的。相当于“技术规格”把实现细节留在正文把决策信息放进元数据。2.3 参数合约一份价值极高的JSON Schema参数设计直接影响模型调用的成功率。我看到很多初学者把参数定义得很粗比如一个技能只写一个input字符串字段让模型自己把参数拼进去。结果就是模型自由发挥每次传参格式都不一样。我现在的原则是参数尽量结构化但不要过度拆。比如搜索技能只需要query、domain、count三个字段每一个都有类型、默认值和取值范围。模型拿到这样的结构传参几乎不会出错。还有一个细节description字段里要写“建议控制在30字以内”这类约束模型真的会遵守。你写“query 是搜索词”它会传一个完整句子你写“搜索词建议控制在30字以内”它就会尝试精简关键词。这算是提示工程在Schema层面的应用实测很有用。另外所有参数尽量给默认值。模型如果拿不准某个非必填字段就不会填你的程序要有兜底逻辑。例如count默认5domain默认空字符串这样调度器永远能收到合法参数。2.4 技能描述怎么写调用率才高技能描述是影响模型决策的最重要因素没有之一。我对比过两种写法写法效果“提供网页搜索服务支持关键词查询”模型经常在应该搜索的知识问题上不调用或者乱调用“当用户需要获取最新资讯、查询实时信息时使用知识性问答请直接回答”明显更能把握调用时机核心技巧是描述里要有触发词比如“最新资讯”“实时信息”这类词等于给模型装了感应器。同时要有负向排除告诉模型哪些场景不该用它。模型在决策时其实是在做文本匹配触发词越明确匹配准确率越高。我还有一个习惯每个技能描述里写一个典型示例场景比如“例如‘帮我查一下今天某公司股价’或‘搜索某某教程的最新版’”。示例相当于给模型提供了一个小样本它会更自信地选择这个技能。3. 加载器实现把技能变成Agent的能力3.1 加载流程扫描、解析、校验、注册有了技能包接下来要解决的是怎么把它们装进Agent。我实现了一个轻量级加载器整体流程分四步扫描技能目录找到所有SKILL.md文件解析frontmatter提取技能名、描述、参数Schema校验必需字段缺失的直接跳过并记录警告注册到内存中的技能表供调度器使用。这个流程听起来简单但每一个环节都有细节。比如扫描时你要处理“一个技能被禁用”的情况我采用约定技能目录下放一个.disabled标记文件扫描时遇到就跳过。这样不需要改代码也不用删目录临时禁用特别方便。3.2 核心代码实现技能加载器的核心代码不长我直接贴一个简化版本import yaml from pathlib import Path SKILL_ROOT Path(./skills) def parse_skill_md(path: Path): 解析 SKILL.md返回 (frontmatter, 正文) text path.read_text(encodingutf-8) if not text.startswith(---): raise ValueError(SKILL.md 必须以frontmatter开头) parts text.split(---, 2) meta yaml.safe_load(parts[1]) body parts[2].strip() if len(parts) 2 else return meta, body def load_skills(): skills [] for md in SKILL_ROOT.glob(*/SKILL.md): # 判断是否被禁用 if (md.parent / .disabled).exists(): print(f[skip] disabled skill: {md.parent.name}) continue try: meta, body parse_skill_md(md) except Exception as exc: print(f[error] parse {md}: {exc}) continue # 必需字段检查 if not meta.get(name) or not meta.get(description): print(f[warn] {md} 缺少name或description) continue skills.append({ name: meta[name], description: meta[description], parameters: meta.get(parameters, {}), path: md.parent, doc: body, }) return skills这段代码大概60行已经能应付绝大多数场景。你可能注意到glob(*/SKILL.md)只扫描一层目录没有递归。这是故意的因为我不支持技能嵌套技能那样会让加载逻辑复杂化。技能保持扁平组合能力通过后面的“技能编排”解决。3.3 动态决策让模型自己选技能加载器把技能表准备好之后下一步是把技能列表注入到模型的对话上下文中。通常的做法是先将每个技能的name和description合并成一个列表然后拼进系统提示词或者作为工具列表的一部分。我用的格式如下[ { name: web-search, description: 当用户需要获取最新资讯、查询实时信息、搜索网页内容时使用此技能。, parameters: { type: object, properties: { query: {type: string, description: 搜索词}, count: {type: integer, default: 5} }, required: [query] } } ]模型每次请求前Agent框架会生成一个待调用的指令结构大概是{skill: web-search, arguments: {query: ...}}。调度器收到指令后在技能表中查找到对应的技能目录然后执行入口脚本再把运行结果返回给模型。我建议不要把全部技能一次性塞给模型而是做一个粗粒度分组。比如默认加载通用技能遇到文档处理任务时再把文档相关的几个技能拼进来。这样既能控制上下文长度又能让模型在小范围内做精确选择效果比“一口气给50个技能”好不少。3.4 实测效果有技能和没技能的对比我拿一个真实场景跑过对比让Agent完成“搜索某产品的最新评测然后总结成三句话”。没有技能库时模型要么直接编造要么需要我在提示词里手写一大段搜索API的调用说明。有了web-search技能后模型自动识别“最新评测”触发词选择技能并正确传参返回结果后我自己再经过一层摘要技能整个流程非常顺。另一个变化是提示词长度。以前工具说明要占系统提示词一大半经常挤占任务指令的空间。现在提示词里只保留技能清单和一句“按需调用技能”上下文清爽很多模型更关注任务本身。这不是说技能机制是银弹。说到底它只是把工具的组织方式捋顺了模型本身的推理能力该什么样还是什么样。但在工程层面Azure式的调用混乱问题确实减少了一个数量级。4. 实战中的典型问题与排查技巧4.1 路径与命名导致的诡异故障技能加载器第一次在同事电脑上跑的时候出现了SKILL.md正常但入口脚本找不到的情况。排查半天发现是目录名带空格subprocess.run([python, skill_path])直接崩了。后来我做了两个规定技能目录名必须是小写字母加中划线入口文件路径统一从SKILL.md所在目录推导不接收外部传入的相对路径。还有一次是Windows和Linux的路径分隔符问题。我在Linux上写的技能脚本用Path拼接路径没问题到了Windows上某个测试函数里硬编码/就出问题了。这类问题防不胜防最好的办法是所有路径操作都走pathlib并且技能测试必须在目标运行环境跑一遍。4.2 技能描述太长模型开始乱选技能描述一开始写得很详细每个都超过300字甚至有一些场景示例。结果发现模型的选择准确率不升反降经常在两个技能之间犹豫或者干脆选错。原因不难理解描述过长核心触发词被淹没模型要处理的文本噪声变多了。后来我把描述压缩到150字以内保证第一句话就是触发条件后面最多补一句限制或示例。挤出来的详细内容放到SKILL.md正文里模型不需要读只有人才需要读。这条经验后来成了我的铁律给模型的描述要短、准、狠。4.3 参数合约和实际实现脱节比较常见的问题是SKILL.md里的parameters定义了date字段要求YYYY-MM-DD格式但入口脚本里用的是datetime对象又没有做字符串解析。模型传了2025-03-01脚本报错Agent返回乱糟糟的错误信息。为了根治我在调度器和技能入口之间加了一层参数校验按照JSON Schema校验后再执行。校验不过的情况直接生成友好的错误信息返回给模型让它重新传参。这层校验一开始用现成的jsonschema库后面发现对于简单技能有点重就自己写了一个轻量校验器只检查必填字段、类型和取值范围。够用就好不想为了一个技能库引入一堆依赖。4.4 技能冲突同名覆盖和标签混乱技能多了以后很容易出现两个技能名字一样但功能不同的情况。我的加载器之前是遍历目录直接按name存字典后来发现后面的会把前面的覆盖掉。解决办法是加了命名空间一个技能包在仓库里要有唯一ID形如search/web-search这样的group/name形式。在传给模型时仍然只传短名字但在内部调度表里用完整ID避免覆盖。另一个相关问题是标签体系混乱。一开始大家随意打标签后来筛技能时基本没用。现在规定一个技能最多三个标签且必须是预先定义好的标签枚举比如search、document、automation这样才具备筛选价值。4.5 依赖隔离多个技能撞车技能多了以后依赖冲突是早晚的事。某个技能要pandas 1.x另一个技能要pandas 2.x同一个环境里直接装会打架。轻量方案是按进程隔离也就是调度器调用技能时在子进程里执行对应脚本且该技能使用自己固定的虚拟环境。我实际用的方案更朴素能不用重依赖的技能就不用非要用的单独建虚拟环境并在SKILL.md里写明环境名。调度器根据skill_env字段找到对应的Python解释器再执行入口脚本。虽然慢一点但稳定是最重要的。5. 如何写好一个高质量技能5.1 范围要小目标要单一一个技能只做一件事这是我从失败案例里得出的教训。最早我把“处理PDF”写成一个技能包含解析、提取、摘要、翻译四个功能。模型在调用时经常搞不清到底用哪个参数来控制行为传错参数的概率很高。拆成pdf-text-extract、pdf-summary、pdf-translate三个技能后每个技能职责清晰模型选择也就准确了。拆分的代价是技能数量变多但描述变简单了。模型更喜欢明确的选项而不是一个复杂的多功能开关。别担心技能太多你可以通过标签和分组来管理数量。5.2 容易照抄的技能结构结合自己的经验我整理了一个技能编写模板新技能照着这个套路写基本不会跑偏1. SKILL.md frontmatter - name: 唯一短名 - description: 第一句触发条件第二句能力最后一句副作用边界 - parameters: JSON Schema必须提供默认值和取值范围 - version: 语义化版本号 2. 实现脚本 - 入口函数或CLI从stdin或参数接收输入 - 输出统一为JSON便于调度器解析 - 禁止在脚本里print非JSON内容 3. requirements.txt - 列出所有依赖注明版本范围 4. tests/ - 至少一组典型输入和期望输出 - 用fixtures模拟真实数据入口脚本的输出格式我非常强调统一JSON。很多技能实现者喜欢在代码里print(正在搜索...)这类日志输出结果混进JSON里调度器解析直接失败。正确做法是日志输出到stderrstdout只留给结构化数据这是所有技能实现必须遵守的约定。5.3 测试与回归把技能当代码对待技能不是一次性写的它会持续被模型调用也会被其他开发者修改。每次改动都可能引入问题。我在每个技能目录下放了一些轻量测试脚本改动后本地运行一次确认基本功能没坏再提交。虽然做不到自动化CI的全套流程但至少能挡住大部分低级错误。有一个技巧很实用测试时把Agent的决策能力也纳入覆盖。简单做法是准备几段典型的用户问题比如“查一下最新天气”“把这个PDF总结一下”然后看模型最终选择了哪个技能。如果正确答案没被选上多半是技能描述需要优化。这类回归测试不需要代码就是整理一组问法手动跑一遍非常值得。6. 后续扩展方向6.1 技能版本与技能市场技能库用了一段时间后我觉得可以再往前走一步做技能分发。为每个技能增加作者、发布时间、使用次数等元数据形成一个可浏览的技能市场。不过这个优先级不是很高因为核心团队用的话仓库本身已经够用了。对个人开发者来说我更推荐先把版本管理做好。每次修改技能时应当更新version字段逗号之间不改也别动。这样一旦线上出现问题可以快速确认Agent当前用的是哪个版本的技能避免“昨天还能用今天就不能用”还查不出原因。6.2 技能组合与工作流单个技能解决单点问题但真实任务往往是多个技能串联。比如“搜索最新资讯并生成摘要”需要先调用web-search再调用summarize。我现在会在Agent提示词里描述这类组合路径让模型自己编排调用顺序效果还行。更进一步可以在技能库里加入简单的“工作流文件”用DSL描述技能之间的依赖顺序和参数传递。不过说实话这套机制做重了就容易变成另一个编排框架而技能库的核心价值仍然是“组织能力”不是“编排流程”。我也不建议一开始就搞工作流等技能数量和组合需求都稳定后再考虑。6.3 跨框架兼容从技能到标准协议的桥梁现在的技能格式五花八门换一个Agent框架往往意味着重新封装一遍工具。最省事的做法是让技能底层适配标准工具调用协议在调度器层做一层转换对外输出成为标准格式。这样技能库既服务于本地方案也能接入其他协议生态避免被单一平台锁定。我在自己的实现里做了一层薄薄的适配技能执行器不关心外层是谁在调用只暴露一个统一的run(json_input) - json_output接口。任何Agent框架只需要用标准方式调用这个接口即可。这不仅是兼容性问题也是一种架构纪律——技能作为能力原子必须保持对外接口稳定。实操中的个人体会折腾 agent-skills 这段过程最大的收获不是代码而是把Agent能力组织这件事想明白了。工具再多如果不解决好“什么时候用、怎么用、用错了怎么办”这三件事模型的输出质量就会永远卡在一个不上不下的位置。技能库未必是唯一答案但它给我提供了一个很稳定的工程抓手。最后再分享一个小技巧在技能调试阶段别一上来就接Agent先写一个命令行脚本直接调用技能入口确认输入输出都稳了再连模型。这样能把“模型决策问题”和“技能实现问题”彻底隔离开排查问题会轻松很多。