最近这半年我在折腾各种Agent项目的过程中对“skills”这个词有了完全不一样的理解。如果你混迹在AI开发圈或各种智能体交流群里一定见过越来越多类似“技能包”“技能库”“给Agent装上skills”的说法。这个看似普通的英文单词正在悄悄改变我们搭智能应用的方式。简单说现在讨论的skills不是指人的能力也不是指某个具体模型的本领而是指AI智能体可复用的结构化技能模块。它可以是一份精心编写的提示词模板也可以是一组带描述文件的函数集甚至是一个包含依赖和独立运行逻辑的代码包。核心逻辑就一句话让模型不再靠“临场发挥”而是像工具箱里抽扳手一样在合适的场景自动调用对应技能。这篇文章适合正在做Agent开发的人以及被各种Function Calling、插件机制搞得一头雾水的初学者。我要讲的不是那种挂在GitHub上看看就完事的开源教程而是一整套我自己踩过坑、沉淀下来的技能设计思路和实操方法。从为什么需要技能机制到目录怎么建、描述怎么写得让模型“秒懂”再到完整案例和排查套路全部摊开讲。1. 内容整体设计与思路拆解1.1 从“模型硬扛”到“技能外包”机制演进的逻辑回顾一下过去两年做AI应用的路子基本可以分成三个阶段。第一个阶段是“纯提示词时代”。所有业务逻辑全塞进System Prompt里希望模型记住规则、扮演角色、按格式输出。这种做法对付简单任务没问题但一旦业务复杂起来提示词就会变成几千字的“小论文”。模型不仅要理解任务还要在长下文里寻找关键约束既要推理又要调用外部数据效果可想而知——上下文越长指令遵循率越低幻觉越重。第二个阶段是“Function Calling时代”。开发者把能力封装成函数告诉模型“有这些工具可用”让模型自己决定要不要调用、传什么参数。这解决了“让模型动手做事”的问题但新的麻烦也来了函数一多列表塞得满满当当光是描述就得写一大堆调用准确率开始下降。而且函数是全局的所有任务都能看到所有函数模型经常“选错工具”。第三个阶段就是我们正在经历的“Skills时代”。它的核心变化是把功能、元数据、说明文档绑成一个独立单元模型在任务开始前先去“技能库”里扫一遍根据当前任务挑出一到几个最相关的技能再基于技能内容决定怎么执行。这就像你雇佣了一个助手他不是什么都现学现卖而是背后有一个分类清楚的工具墙每一个工具都贴着使用说明看一眼就知道该抽哪把。说白了Skill机制解决的是两个核心痛点如何让模型在合适的时机发现合适的工具以及如何让工具的使用成本降到最低。它不做复杂的推理重活而是把“选择”和“执行”分开——选择由模型的语义理解完成执行交给具体代码逻辑各司其职稳定性大幅提升。1.2 为什么需要“技能描述”这种元数据很多人第一次接触skill结构时会觉得奇怪明明核心是代码为什么还要单独写一份SKILL.md直接写函数不就行了这里要理解一个关键点在Agent场景下模型看到的和你看到的不是同一份东西。你看到的是目录结构、Python文件、配置文件模型看到的是一段被填充进上下文的文本。它通过这段文本来“认识”一个技能——什么时候该用、它能做什么、需要提供什么参数、限制条件是什么。所以技能描述文件是整个机制的信息桥梁它决定了模型能不能正确调用技能。代码写得再优雅如果描述写得含糊模型依然会在对的场景里假装没看见。从技术角度看大部分skill系统的运行流程是Agent收到用户任务后会先读取技能库索引根据任务语义做匹配筛选把得分最高的技能内容加载到上下文中如果技能是代码类型还会把入参、返回值、运行环境一并提供给模型。因此写作描述的过程本质上是在“教”模型什么时候该用你这份功能。而描述的好坏直接决定了Agent的行为边界。这也是我在实操中反复强调的“倒挂金字塔”原则——技能描述越上一层的越简短克制越下一层的越详细精确。最外层的索引只需有一句话概括让模型能精准匹配到具体使用说明时再展开参数细节、调用方式和注意事项到了代码层面就该有完整的错误处理和边界判断。如果反过来把大量细节堆在索引层模型反而会迷失重点。2. 核心细节解析与实操要点2.1 技能库的标准目录与文件结构一个规范的技能包通常长这样my-skill/ ├── SKILL.md ├── requirements.txt ├── script.py ├── template/ │ └── prompt_template.j2 └── assets/ └── reference_data.json先说最核心的两个文件。SKILL.md是技能的“名片”里面写清楚这个技能叫什么、何时用、怎么用、要注意什么。它采用的是YAML前置元数据加Markdown正文的结构前半段是机器能读的元信息后半段是模型能读的说明文本。requirements.txt是Python依赖清单哪个技术的技能就配哪个依赖库。这个文件很重要因为很多Agent框架在加载技能时会自动创建虚拟环境并安装依赖保证技能能独立运行不污染主环境。再往下是可选的模板目录和资源目录。比如做文本改写类的技能可以在template/里放Jinja2模板做数据分析类的技能可以在assets/里放参考数据集。这些额外资源的好处是让技能真正“即插即用”——不只是给模型讲道理而是给模型提供可以直接上手操作的材料。2.2 SKILL.md清单文件的写作技巧SKILL.md是技能的灵魂也是最容易写砸的地方。我见过很多新手要么把描述写得又长又空要么把代码细节全塞进去结果模型根本抓不住重点。我推荐的结构是开头用三五行字说明“这个技能是什么”和“什么时候别用”紧接着写用法示例最后写参数和注意事项。关键在开头那几句话——这是模型做技能匹配时的主要依据。举个我实际用过的例子一个给代码库生成CHANGELOG的技能开头我是这样写的name: generate_changelog description: 根据Git提交记录生成CHANGELOG仅在用户需要查看版本变更、发布日志时使用。很短但信息量足够。模型看到“版本变更”“发布日志”这两个关键词就能在遇到相关任务时想起它。接下来的正文部分要有“两步走”的节奏。第一步用一句话讲场景比如“用户在发布前需要整理最近一段时间的代码变更”第二步直接给调用示例告诉模型先收集哪些信息、用什么命令、输出格式是什么。示例的力量远大于抽象描述模型会照着示例去组织自己的行为。最后是“注意”部分。这一块是我个人的秘密武器。我会明确写“不要做的事”比如“不要在没有Git仓库的目录下运行”“不要主动修改用户的未提交文件”。你可能会问这些限制有必要吗太有必要了。模型在执行任务时有一种“过度自信”倾向如果不清不楚它会为了达成目标去做一些越界操作。你把这些约束写得越具体它越不容易乱来。2.3 代码模块的通用设计规范技能里的代码跟普通项目代码不太一样。普通代码追求功能完整技能里的代码还要额外考虑两件事如何被模型快速理解和如何安全地应对意外情况。为了让模型能快速理解代码逻辑我建议所有函数都必须有清晰的docstring和类型注解。这倒不是为了代码优美而是模型作为“阅读者”通常会先扫一遍函数签名和注释再决定怎么调用。如果你用data_list这种含糊的变量名模型往往会猜测语义不怎么靠谱。更稳妥的做法是把公开函数精简到一两个入口把复杂度隐藏在函数内部模型只看得到“简单接口”执行起来就稳定得多。第二个重点是异常处理。在Agent场景下代码的输入通常来自模型生成而模型的输出永远可能有小偏差。比如它可能传了不存在的文件路径可能把参数类型搞错甚至可能在不合适的时机调用技能。所以你需要给每个函数设计“宽进严出”的接口入参做基础校验内部处理做好兜底实在不行就返回明确错误信息而不是抛出堆栈。我的经验法则是一段技能代码里正常逻辑占一半参数校验和边界处理占另一半。这样写出来的技能模型随便怎么“霍霍”都不会炸掉主流程。2.4 上下文窗口利用与MCP等机制的联动技能机制不是孤立的它跟MCP这类工具调用规范是互补关系。MCP负责定义“模型如何调用外部工具”的协议Skill负责定义“哪些能力以什么方式组织在一起”。一个管传输层一个管应用层配合起来非常顺。在实际使用中还有一点容易被忽略上下文窗口不是拿来无限塞技能内容的。即使你给Agent挂了一百个技能模型每次能认真读的上下文也是有限的。你需要把每个技能的描述控制在合理长度——我的底线是SKILL.md不超过200行超过的要么精简描述要么拆成子技能。否则技能库一膨胀光是扫描技能描述就占用大量token模型的有效注意力反而变少最终效果不升反降。MCP的引入也带来了一个变化你不必把技能代码全放在本地。你可以通过MCP连接远程服务让技能变成一个“调用远端能力”的适配层。这样做的好处是技能描述仍然轻量真正的计算与数据服务都在远端完成。对团队协作而言这意味着一份技能可以被多个项目共用更新一次全部生效。3. 实操过程与核心环节实现3.1 案例拆解做一个“周报收集与汇总”技能理论讲再多不如动手做一遍。我拿一个我最近在工作中实际用到的技能来演示周报收集与汇总。需求背景很常见团队十个人每周五要交周报格式五花八门我每周一得花一小时把所有人的内容手工汇总到一个文档里。传统的自动化方案是写脚本遍历邮箱或文件夹但问题是大家汇报格式不统一脚本处理起来非常费劲。用Skills机制解决这个问题的思路就完全不一样了。我不需要做一个“万能解析器”而是让Agent先执行“收集”技能把所有周报文档拉取到指定目录再执行“解析总结”技能让模型读懂每一份内容提取关键信息最后按统一模板生成汇总文档。人工要做的只剩核对和少量补充时间从一小时缩到了十分钟。这个任务拆出了两个子技能collect_reports和summarize_reports。collect_reports负责从指定邮箱或网盘下载文件按人员和时间归类summarize_reports负责读文档、抓重点、按模板输出。两个技能各干各的互相独立以后任何一个都能单独复用。3.2 安装与清单配置的完整过程我先说collect_reports这个技能怎么搭。目录结构如下collect_reports/ ├── SKILL.md ├── requirements.txt └── script.pyrequirements.txt里写上依赖比如用IMAP协议读邮件的话就写上imaplib这其实是标准库不需要装如果接飞书或企业微信的API就得写对应的SDK包。我的例子中用了网盘API所以写的是requests。SKILL.md的核心内容长这样--- name: collect_reports description: 从指定邮件或网盘收集团队周报文件按人员和日期归类到本地目录仅在用户需要汇总周报、收集他人提交的文件时使用。 ---正文里我会强调输入参数报告目录、日期范围、来源类型邮件/网盘。执行步骤先读取配置连接来源下载附件重命名归档。注意事项不要删除源文件文件重名时保留时间戳下载失败时继续执行并记入日志。3.3 核心代码实现及参数设计script.py的核心函数我这样写import os import re from datetime import datetime from pathlib import Path from typing import Dict, List, Optional def collect_reports( source_uri: str, report_dir: str ./reports, date_range: Optional[tuple] None, file_pattern: str r\.(docx?|pdf|md)$ ) - Dict[str, List[str]]: 从source_uri指向的来源邮件或网盘中收集周报文件。 Args: source_uri: 来源地址例如 imap://userexample.com 或网盘分享链接 report_dir: 存放报告的本地目录 date_range: 需要收集的日期范围例如 (2025-04-01, 2025-04-15) file_pattern: 匹配文件类型的正则 Returns: 按人员名称分组的文件路径字典例如 {zhangsan: [reports/zhangsan/2025-04-11.md], ...} os.makedirs(report_dir, exist_okTrue) # 伪代码连接来源遍历文件列表 # 真实实现根据来源类型调用对应API或标准库 result {} # 把文件下载到临时目录 tmp_files _download_files(source_uri, cache_dir.cache) for file_path in tmp_files: if not re.search(file_pattern, file_path): continue # 从文件名或内容中识别人员 person _extract_person_name(file_path) date_str _extract_report_date(file_path) if date_range and not (_in_range(date_str, date_range)): continue target_dir Path(report_dir) / person target_dir.mkdir(parentsTrue, exist_okTrue) # 归档并重命名 final_path target_dir / f{date_str}_{Path(file_path).name} os.rename(file_path, final_path) result.setdefault(person, []).append(str(final_path)) return result这里有几个设计点值得细说。第一个是返回值结构。为什么返回Dict[str, List[str]]而不是简单返回文件列表因为后续的summarize_reports技能需要按人员去遍历模型拿到这种结构化结果可以直接用“人员”作为索引减少二次解析成本。你在设计技能接口时一定要思考下一个技能或下一轮模型调用想要什么形状的数据别只想着当前这步怎么方便。第二个是file_pattern参数。我用正则来限定收集的文件类型不匹配的直接跳过。这样即使用户把私人照片、会议纪要都放在同一个网盘目录也不会混进来。这种“前置筛选”要比“后置清理”省事得多。第三个是临时目录.cache。下载下来的文件先落临时目录等过滤和归档全部完成后再统一处理。为什么要这样因为邮件或网盘API的下载操作通常比较慢如果每下载一个文件就重命名归档中间任何一步出错都容易留下半成品。先集中下载再统一归档中断恢复也更方便。3.4 汇总技能的提示词设计与输出控制再来看看summarize_reports。这个技能是纯提示词型代码不是重点重点是模板。SKILL.md的正文我写得格外仔细当用户说“汇总周报”或“整理大家这周的工作”时使用本技能。 先按人员读取目录下所有周报文件对每一份文件执行提取流程 1. 识别本周完成事项用“项目名 一句话结果”格式输出。 2. 识别下周计划用“方向 预期产出”格式输出。 3. 识别风险与阻塞直接原样摘录不要改写。 4. 如果没有某类信息写“无”不要编造。 输出格式为Markdown表格按人员分行每行包含 | 人员 | 本周完成 | 下周计划 | 风险与阻塞 | 对于本周完成事项超过三条的人员在表格下方用无序列表补充细节每条不超过50字。这里的关键词是“不要编造”和“原样摘录”。周报汇总最怕模型发挥创造力把“张三说本周在调接口”扩展成“张三完成了接口性能优化并大幅提升了稳定性”。所以我在描述里明确约束——信息不足就写“无”不要脑补。输出用表格也是个好策略。模型看到明确的格式要求会自觉收敛输出内容而且表格天然适合汇总类场景后面要转成Excel或在线文档也方便。3.5 完整调用链路的本地实测记录在本地环境下我用一个简单的Agent框架把这两个技能串起来跑了三次真实数据。第一次试运行用户指令是“帮我汇总上周大家的周报来源是默认邮箱”。Agent先匹配到collect_reports执行下载归档了9个人的文件其中一人这周没交所以目录里只有8份。接着匹配到summarize_reports读取8份文档后生成了汇总表格。整个流程大概40秒模型调用了两轮一次选技能一次总结。第二次试运行我没有改任何代码只是把邮箱换成网盘链接Agent在读取技能描述后自动识别了来源差异调用了一个参数不同的接口最终结果一致。这说明技能描述里写清“来源类型”这个入参模型就能自适应不同数据源。第三次试运行我做了一个破坏性实验——把一个文件的内容改成只有“暂无”两个字。结果summarize_reports输出的表格里那行“本周完成”就是“暂无”没有乱编也没有报错。这个表现让我很满意说明技能约束真实生效了。4. 常见问题与排查技巧实录4.1 技能召不回模型就是不选它这是最让人头疼的问题技能挂在库里但模型执行任务时压根不看它或者看了一圈把它排在了最后。要排查这件事先把技能描述的第一句话拿出来审问一遍它是否包含用户可能说的原文词如果用户说“汇总周报”你的描述里只写了“聚合团队提交的周期性工作报告”匹配度自然低。模型做技能匹配时本质上是在做语义相似度计算你的描述用词与真实需求的词汇重合度越高召回概率越大。我惯用的排查方法是“角色扮演测试”。把自己当成模型只看技能描述不看代码问自己三个问题这个技能是干嘛的什么场景用什么场景千万别用如果看完描述后你得想三秒才反应得过来那这个描述就不合格。好的描述应该让模型一眼看穿连猜都不用猜。另外技能库里同类技能过多也会互相干扰。我见过有人一口气挂了五六个文本处理类技能描述都差不多模型选择困难频繁挑错。这类问题最好的解法是合并同类项——描述相近的合并成一个技能用参数区分具体模式而不是让模型做复杂抉择。4.2 技能被选中了但模型不会用参数第二个高频问题技能选对了参数却传得乱七八糟。比如collect_reports提供date_range参数模型却传了一个字符串“上周”而不是元组(2025-04-01, 2025-04-15)。这不是模型笨而是你的描述里没有明确参数的格式要求。解决方法是三层保险。第一层在SKILL.md中给出参数示例直接展示一个完整调用。第二层在代码里面做宽容处理——如果收到字符串就尝试做日期解析或关键词到日期的映射实在解析不了再报错。第三层如果你的Agent框架支持定义参数schema一定要把类型、枚举值、默认值写清楚。模型对结构化的约束比自然语言的描述更敏感。4.3 输出不稳定的问题与标准化模板约束技能输出不稳定今天格式完全符合预期明天同一份输入生成的格式就跑偏这个问题我也遇到过好多次。原因基本在模板描述不够刚性。你写“用Markdown表格输出”模型可能正常输出表格但也可能为了“美观”给你加粗个标题、加个分隔线、再来个简介段落。表面上看没什么但下游程序要是按固定格式解析就会被这些“自由发挥”坑惨。对策是把模板写得更“窄”。比如我写“直接输出表格不要添加任何前后缀”模型往往就会真的只输出一个表格。为了确保模型不自由发挥也可以把格式说明那一小段作为用户消息的一部分在调用时重复强调效果比放在System Prompt里要好。4.4 测试方法与调试技巧技能写完了你没法像普通程序那样直接启动调试因为模型行为有随机性。我形成了自己的测试习惯每改一版描述至少跑三个不同的同类任务再跑一个不相关的任务看模型是否能在相关任务上稳定触发、在无关任务上果断忽略。这一条特别重要——技能调用的“拒绝率”跟“命中率”同等重要。如果无关任务也经常误触发就说明你的描述边界写得太宽了容易引发意料之外的行为。调试过程中我还会开启Agent框架的日志输出查看每一轮模型调用的token消耗。技能描述占用的字节数直接影响总token消耗如果一次任务技能部分就占了几千token效果还不理想就该考虑精简描述了。5. 个人体会与后续扩展方向这段时间做下来最大的体会是技能机制真正改变了Agent开发的分工方式。以前我们把所有逻辑揉进一个巨大的提示词里模型一边做推理一边记规则一边想格式很容易顾此失彼。现在把每种能力拆成独立技能每个技能只聚焦一件事模型的任务变成“先选对工具再按工具里的说明执行”复杂度被大幅降低。大家在做自己的技能库时也别总想着一下子上百个技能才算完整。技能的生命力不在于数量而在于每个技能是否干得漂亮。我也一直提醒自己——如果一个技能描述缩不短、功能拆不开、调用连着上一串前置条件那就说明这个技能设计得还不够“原子”应该再分细一点。后续可以扩展的方向不少。我最近在尝试把几个常用技能升级成MCP服务让团队其他人也能通过统一的工具入口直接调用。还打算对一个高频技能做A/B测试同一功能写两个版本描述随机加载其一跑一批任务做效果对比选优留存。这个方法也推荐给想系统化打磨技能的人数据比感觉可靠得多。最后再分享一个实际操作中的小技巧技能描述写完别急着挂到正式Agent里先拿一个便宜的模型版本跑几遍。如果便宜模型都能正确选中技能、按规范调用换成更强模型时表现会更稳。如果便宜模型都跑不明白问题通常出在你写的描述而不是模型能力这时候去改描述效率远远高于去换模型。