★ FEATURED ARTICLE 1. 为什么Agent离不开技能包先聊个现象。最近半年我一直在折腾各种Agent工作流从简单的提示词模板、到Function Calling、再到现在的Skills机制最大的感受是大模型的“能力”其实分成两层一层是它脑子里装的常识另一层是它能稳定执行的流程。常识层面各家模型已经拉不开太大差距了真正决定一个Agent好不好用的是后面这层——能不能按一个固定的、可复用的方式把活儿干完。在没有技能包之前我每次让Agent做一件稍微复杂点的事都要经历一场“拉锯战”。比如让它根据我的周记生成周报第一次回复是标准的三段式第二次变成了一段式第三次开始自作主张加上了下周计划。不是模型变笨了而是每次对话都是“重新开始”我那些口头交代的工作习惯、格式偏好、边界约束它根本没有沉淀下来。这就很像你让一个临时工干活每次都得从头讲一遍要求他干出来的东西还每次都不太一样而技能包做的事相当于把某个岗位的“岗位说明书 标准作业程序 配套工具”一次性交给了模型。技能包这个概念其实不难理解它就是一个结构化的文件夹里面包含一份指令文档通常叫SKILL.md告诉模型“这是个什么技能、什么时候该用、按什么流程做、输出成什么样”还可以附带脚本、模板、参考文件和依赖清单让模型在需要时能真正动手处理数据而不仅仅是“凭感觉生成文本”。它的核心价值在于把原本只存在于人脑里的隐性经验变成了Agent能稳定读取的显性资产。这篇文章的受众我觉得有两类人。一类是正在用Claude或类似Agent平台做自动化、做内容生产、做内部工具链的开发者技能包能帮你把碎片化的工作流固化下来。另一类是自己搭Agent、对接API的工程化玩家会需要掌握技能的目录组织、指令编写、脚本联动这些细节。我下面讲的东西都偏实操不会绕理论直接讲我踩过坑之后总结出来的那套做法。2. 技能包的核心细节从设计到落地2.1 技能包的目录结构到底长什么样一个标准技能包从物理形态上看就是一个目录。目录名字建议全小写加短横线命名法比如weekly-report-generator别用大写字母、空格、下划线因为很多Agent框架对技能名有严格的格式约束我最早用Weekly_Report命名结果在部分工具里直接不被识别排查了半天路径问题才发现是命名惹的祸。目录内部的分工大致是这样文件/目录作用是否必需SKILL.md技能的“说明书”包含元信息和给模型的指令正文必需scripts/存放可执行脚本模型可调用按需assets/放模板、静态参考文件按需requirements.txt依赖第三方Python库时声明按需很多人误以为技能包只是个“高级提示词”其实不是这么简单。当Agent的推理能力和工具调用能力结合起来时SKILL.md负责定义“该怎么思考”scripts负责处理“该执行什么动作”assets负责提供“该参考什么素材”。三者配合才能让技能从“说得漂亮”变成“干得靠谱”。我之前做过一个生成会议纪要的技能刚开始只有SKILL.md模型能听懂要做纪要但遇到几十页的录音转写文本时它会读得磕磕绊绊而且摘要里经常混进无关内容。后来我在scripts里放了一个基于关键词过滤的预处理器又给assets放了一个纪要模板效果立刻就不一样了。这给我的启发是凡是涉及到数据处理的环节尽量别依赖模型自由发挥用脚本把“脏活”干了模型只负责判断和表达这才是技能包的正确打开方式。2.2 为何SKILL.md是技能包的灵魂我见过不少人写技能包最上心的反而是scripts里的代码对SKILL.md反而很敷衍。这个思路是反的。Agent拿到一个技能包之后它并不会自动知道自己该干什么一切行为起点都是SKILL.md那份说明文档。里面写得含糊后面写再多代码也没用。SKILL.md的结构一般分成两部分YAML格式的frontmatter元信息和Markdown正文。frontmatter里最要紧的字段是name和description。name要跟目录名保持一致description则决定了模型“什么时候会想起这个技能”。这个字段很微妙写得太泛比如“生成周报”模型在别的场景下也可能错误触发写得太窄比如“根据用户提供的JSON格式的任务记录生成包含完成状态、困难点、明日计划的周报Markdown文件”模型反而能在该用的时候自动匹配上。一定要记住description不是给人看的是给模型的触发条件写的。正文部分则是模型执行技能的完整说明书。我推荐按这种顺序组织技能的触发场景与目标一句话说清楚。输入需要哪些信息从哪里获取。执行步骤分步骤引导第几步干什么别让模型跳跃。输出格式给出明确模板或结构最好有示例。注意事项明确失败条件和边界告诉模型什么不能做。里面每个动作尽量用祈使句比如“从用户消息中提取目标日期”“调用scripts/summarize.py对笔记做摘要”“将结果填入下面的模板”这比“你应该尽可能地分析用户的需求”这种废话有用得多。模型对“动词引导式”的指令响应率明显更高这是我实测下来的经验。2.3 让技能真正生效的参数规则技能包在执行时经常需要接收外部输入。比如模型要根据用户的消息去生成周报那用户消息里的原始记录就要能被SKILL.md里的指令引用到。大多数Agent框架用的占位符风格是双大括号比如{{input}}也有用$variable的具体按平台规范来。这里有个特别容易踩的坑别把占位符和shell变量混为一谈。我最初写了一个技能在SKILL.md里引用某个路径变量时用了$NOTES_FILE结果模型把整个字面量原样传给了脚本脚本自然是读不到文件的。后来统一改成{{notes_file}}再配合前置指令“执行前将{{notes_file}}替换为实际路径”问题就没了。遇到这类问题排查思路很简单先看传给脚本的到底是什么是不是被当成了字符串字面量只要把原始调用日志拉出来看一眼就明白了。还有一点占位符的数量别太多。我见过一个技能包里定义了七八个占位符让模型在执行时逐一填充看起来很灵活但模型经常填错或者漏填。如果可能尽量让脚本自动从标准输入或固定路径读取数据减少人为传参。技能包设计得越“傻瓜化”模型跑起来越稳定。2.4 脚本与工具调用的边界把握什么时候该写脚本什么时候不该写我的判断原则很简单凡是规则明确的处理交给脚本凡是需要理解和判断的地方留给模型。比如做周报提取每个任务的完成状态是规则明确的交给脚本为任务写一句“存在风险的原因分析”这是理解与判断的活应该由模型完成。脚本本身的代码不需要写得多花哨但要注意三点。第一路径别写死尽量用相对路径或者通过参数传入第二输出尽量标准化最好能让模型直接读取的结果是JSON或纯文本形式别输出一堆带颜色的日志第三记得做异常处理脚本万一处理失败模型要能理解报错信息而不是看着一堆traceback发呆。我还习惯在脚本里增加一个--dry-run模式。这样在调试技能包时可以先不真正调动模型只用固定输入跑一遍脚本快速确认数据链路是否通畅。这个习惯帮我节省了大量排查时间后面会细说。3. 实操演示从零做一个周报技能包3.1 场景定义与目录初始化讲理论有点干直接上一个完整的示例。就以“周报生成”为场景——这也是我实际工作中用得最多的技能包因为每周五下午写周报这件事枯燥但流程固定特别适合做成技能。需求先定义清楚我平时会在一个notes/目录里随手记一些工作进展格式稀碎有时候是一句话有时候带时间戳偶尔还夹杂个人想法。周报技能要做的是扫描这些零碎记录、筛出跟项目相关的条目、按“本周完成/风险与求助/下周计划”三个维度重新组织最后输出一份Markdown格式的周报文件。目录结构我按前面说的规范来weekly-report-generator/ ├── SKILL.md ├── scripts/ │ └── parse_week.py ├── assets/ │ └── 周报模板.md └── requirements.txt这个结构很简单但每个文件都有明确职责。SKILL.md是顶层指挥脚本负责解析原始笔记模板负责固定输出风格。3.2 编写SKILL.md的完整过程下面是我用下来比较稳定的SKILL.md写法可能跟官方文档推荐的骨架略有不同但更贴近实际使用。--- name: weekly-report-generator description: - 根据用户的零散工作笔记生成结构化周报。适用场景用户提供notes目录下的文本记录 需要整理为本周任务完成情况、风险与求助、下周计划的Markdown周报。 不适用场景用户只是简单询问近况没有提供具体笔记原文或笔记路径时不要调用。 --- # 周报生成技能 ## 任务目标 将用户提供的工作笔记整理为一份信息完整、层次清晰的周报。 ## 输入获取 1. 确认用户是否提供了笔记目录或笔记原文。 2. 如果用户没有提供主动询问不要猜测或编造内容。 3. 优先读取用户指定的文本文件若文件较多调用 scripts/parse_week.py 进行过滤与聚合。 ## 执行步骤 1. 使用脚本汇总 notes 目录下本周新增的条目过滤掉与工作无关的个人记录。 2. 按三个模块组织内容本周完成、风险与求助、下周计划。 3. 从原始记录中提取关键事实使用简洁描述不要复制整段原文。 4. 对风险与求助事项需要给出判断理由而不仅仅是罗列条目。 5. 按照 assets/周报模板.md 的格式填充内容。 ## 输出要求 - 输出格式为 Markdown使用二级标题分隔三个模块。 - 每个模块下使用无序列表每条内容控制在50字以内。 - 不要捏造任何未出现在原始笔记中的事项。 - 如果笔记信息过少少于3条有效事项主动提示用户补充不要强行生成一份空洞的周报。 ## 注意事项 - 务必区分“任务完成”与“任务进行中”不要混为一谈。 - 不要把用户的抱怨或个人情绪内容写进周报。 - 脚本执行失败时先查看错误信息再决定是继续使用模型直接整理还是请用户检查输入。这份SKILL.md里有一个细节值得注意description明确写了“不适用场景”。很多人写description只写什么时候用不写什么时候不能用结果模型经常误触发——聊天时随口提一句“帮我总结下最近工作”模型都会去翻笔记目录。多写一句不适用场景误调用率能降不少。3.3 配套脚本的实现逻辑再看scripts/parse_week.py。这个脚本的核心功能很朴素读入一个笔记目录过滤掉包含“# 杂谈”标记的个人记录按日期提取当前周的条目输出JSON。以下是示例代码用的是Python标准库不需要额外依赖所以requirements.txt其实可以空着这里为了演示路径依赖问题我保留空文件。import json import os import sys import re from datetime import datetime, timedelta def is_personal(line: str) - bool: # 个人记录标记例如“#杂谈”“#生活”跳过这类行 return bool(re.search(r#\s*(杂谈|生活|吐槽), line)) def current_week_range(): today datetime.now() monday today - timedelta(daystoday.weekday()) sunday monday timedelta(days6) return monday.strftime(%Y-%m-%d), sunday.strftime(%Y-%m-%d) def main(notes_dir: str): start, end current_week_range() items [] for filename in sorted(os.listdir(notes_dir)): if not filename.endswith(.md): continue filepath os.path.join(notes_dir, filename) with open(filepath, r, encodingutf-8) as f: lines f.readlines() current_date None for line in lines: line line.strip() if not line: continue date_match re.match(r^\d{4}-\d{2}-\d{2}, line) if date_match: current_date date_match.group(0) continue if is_personal(line): continue if current_date and start current_date end: items.append({date: current_date, content: line}) print(json.dumps(items, ensure_asciiFalse, indent2)) if __name__ __main__: main(sys.argv[1] if len(sys.argv) 1 else ./notes)这个脚本有两点设计值得一提。第一靠Markdown标题里的日期来归类所以我的笔记习惯是每天用2025-06-09这种格式开头正好形成一个人机都能读的规范如果原始数据的格式更乱可以把解析逻辑再加厚但原则不变——脚本只做机械抽取不做语义判断。第二输出直接是JSON模型拿到这个JSON后再按SKILL.md的指引去生成长句和判断分工明确互不干扰。实际调试时我是这样验证脚本的python scripts/parse_week.py ./notes week_data.json然后把week_data.json里的内容喂给模型看它是否按SKILL.md的要求生成周报。这一步把“模型的问题”和“脚本的问题”剥离开来——脚本错了就看看JSON里的条目对不对模型发挥不好就看看是不是指令描述不充分。3.4 让模型真正“看见”并调用技能技能包写完之后怎么让模型在执行任务时主动调用它这里因平台而异但通用的调试路径可以分享几条。如果是自带技能管理界面的环境直接把目录放进去保存就行。然后做一个“触发验证”作为一个用户对模型说“根据我notes目录这周记录生成一份周报”。注意验证时的描述最好跟SKILL.md里的description语义重合这样才能测试触发是否正确。如果模型没有调用技能优先怀疑description匹配问题把description改写后再试一次。另一种排查方法是“强行点名”。直接在对话里提到技能名比如“使用weekly-report-generator这个技能”看模型是否能够进入技能的执行流程。这相当于绕开了触发匹配直接测试技能内部的质量。如果点名能正常执行但自然对话不触发说明问题出在description的写法上而不是技能内容本身。在做技能调用测试时我还会刻意把一些异常情况混进去测试比如故意说“我昨天的笔记丢了你直接帮我写一份周报吧”看模型会不会开始编内容。只要SKILL.md里的“不要编造”写清楚了模型一般会停下来要更多信息如果它直接开始编说明注意事项写得太软得改成更强制性的语句比如“禁止生成任何未出现在笔记中的事项如果信息不完整直接拒绝生成”。4. 常见问题与排查技巧实录4.1 技能没被触发时的处理顺序这是新手最容易遇到的情况技能放上去了但模型好像看不见它。我建议按下面这个排查顺序走一遍先看目录和命名是否符合规范。技能名不能有空格、大写、特殊符号SKILL.md的编码必须是UTF-8别用带BOM的格式。再看description的触发语义这一步占大部分比例描述跟用户真实表达差太远模型自然想不起来。还需要确认技能包是否被正确加载很多平台有技能列表页如果列表里就没有这个技能那一定是物理路径或配置文件的问题跟模型无关。另外一个容易忽视的问题是技能数量过多导致的干扰。当环境里装了十几个技能包时模型对每个技能都能“看见”但触发阈值会变高。我自己的经验是把技能保持在真正高频使用的五六个以内。数量一多技能就纯粹变成了摆设。4.2 模型调用了技能但输出不对味这种情况也很常见触发成功了模型也确实执行了但结果跟期望偏差很大。这时候要分情况查。如果模型产出的是“形式上正确、内容上空泛”的结果大概率是SKILL.md的输出要求写得不够细。光说“使用二级标题分隔三个模块”是不够的最好能在模板文件里把示例逐行写出来。模型很吃示例那一套——给它一个具体的输出样例比告诉它一百条格式化规则都管用。如果模型产出的是“内容有编造”重点检查输入获取这一步。是不是说了一句“优先读取用户指定的文本文件”却没有禁止模型自行推测笔记内容需要在注意事项里明确增加约束禁止推测笔记中未出现的事项。如果模型虽然执行了但脚本没有被调用那问题很可能出在“步骤拆解”上。模型面对一个技能时有时候会选择跳过某些步骤直接生成结果。解决方案是在SKILL.md里增加一个“强制顺序”描述比如“在生成最终周报之前必须运行以下命令完成数据收集否则不能开始写正文”。4.3 技能包之间的冲突与占用技能装多了以后还会出现互相抢活的情况。我遇到过一个具体案例同时装了“周报生成”技能和“会议纪要整理”技能Description里都有“将信息整理成结构化文档”这种泛化表述结果有时让模型整理会议纪要它却触发了周报技能最后输出一个四不像。解决思路不复杂把每个技能的description写得更有区分度。周报技能的触发条件应该强调“notes目录”“历史工作记录”“周报”会议纪要技能则强调“会议录音转写文本”“行动项”。此外还可以在description里加冲突排除句例如“如果用户输入内容包含会议对话转写则不属于本技能范围”。与冲突相关的问题还有依赖缺失。有些技能包会用到第三方库如果不提前声明依赖执行时直接报ModuleNotFoundError模型看到报错基本就两眼一抹黑了。所以requirements.txt不是摆设它既是给人类看的安装说明也是给Agent环境的提示。技能包共享给团队时这点尤其重要。4.4 老手才注意到的性能与安全细节有些坑不是功能性问题但一旦踩到会影响体验。第一大文件别随技能包携带。我见过有人把一个几十MB的行业数据库文件放进assets目录技能包每次加载都慢得让人崩溃。正确的做法是把大文件放到远程或共享存储SKILL.md里写清楚“执行时从某个路径读取”或者用脚本按需下载。第二脚本对异常的处理要完善。如果有外部输入脚本要考虑文件不存在、编码不符、空数据这些情况。模型执行到一半看到脚本报错如果错误信息可读性差它只会反复重试同一个错误操作。给脚本加上异常处理并输出用户能看懂的中文报错能省掉后面一长串的调试时间。第三技能包不要绑定太强的环境假设。比如SKILL.md里写着“读取C:\Users\xxx\notes”这种绝对路径换台电脑或换个用户就废了。写成“从用户本次消息中指定或系统默认的notes目录读取”让模型自己去找鲁棒性会高很多。4.5 常见问题速查表把上面这些经验做成一张速查表方便照着排查现象可能原因解决方法技能列表里找不到命名不合规或目录路径错误检查技能名、目录名、UTF-8编码自然对话不触发description与用户表达不匹配改写description尽量包含触发词和场景点名调用才生效description太窄或太泛增加适用场景与不适用场景的说明输出格式稳定但内容空泛指令正文缺少输出示例在assets里放附带示例的模板文件模型跳过脚本直接生成步骤拆解不够强制在SKILL.md中规定强制步骤顺序多个技能互相抢占description边界不清写清区分条件和排除规则脚本报错后模型停止工作异常处理不足脚本兜底异常并输出可读报错这张表是我自己在调试技能包时对照使用的。把问题归类以后再动手改比盲目重写SKILL.md高效得多。5. 再进一步技能包的工程化管理5.1 版本管理与团队协作技能包一旦多了它本身也变成了需要维护的代码资产。如果你只是自己一个人用目录里放一份就好但如果要做团队协作就得认真对待版本管理。我建议给技能包打上语义化版本号比如weekly-report-generator v1.3.0。在SKILL.md里加一个version字段。每次修改指令或脚本更新一下版本号并在一个CHANGELOG.md里记录变更内容。这样做最大的价值是回归有基准当某个技能忽然失效可以快速对比出是哪个改动引入的回归。团队协作的话可以把技能包推进一个内部仓库用Git管理。每个人拉取后按文档安装依赖就行。还有一个更工程化的做法给技能包写一个manifest.json描述技能名、版本、依赖脚本、环境要求等信息这样被平台加载时可以直接做版本校验。技能工程化做到这一步基本就告别“改了个技能包结果模型行为大变”的噩梦了。5.2 给技能包做自动化回归测试很多人测试技能包靠的是手动问模型几句话觉得差不多能出结果就完事了。我建议把测试变得更可重复准备一组固定的测试用例每个用例包含输入消息、预期输出结构、预期调用的脚本参数。然后用脚本自动把用例跑一遍检查输出是否满足预期的关键规则比如是否包含必需的章节标题、是否没有出现编造的专有名词。这个思路其实很简单——把模型当作一个函数给定输入断言输出。技能包改动后跑一遍全量用例哪个技能被改坏了立刻就知道。我目前的做法是在CI里加一个测试任务每次推送技能包代码变更时自动运行校验。这套流程写起来工作量不大但能防止“改了A技能结果B技能的description冲突导致触发异常”这类问题。5.3 技能包和MCP、Function Calling的分工跟技能包经常一起被提及的是MCP和Function Calling很多人搞不清它们之间的关系。我自己的理解是Function Calling是模型对话中按需调用外部函数的最底层机制灵活但零散MCP是把工具接入做成了统一标准协议让Agent能发现并调用各类外部服务而技能包则是更高层的“行为单元”它内部可以涵盖指令、脚本甚至多个函数调用的编排。用一个生活化的类比来说Function Calling相当于工具箱里的一把螺丝刀MCP是一个标准接口的电源插座技能包则是“换一个水龙头”这份带图纸和步骤的说明书。技能包更适合解决“一个完整任务怎么从头到尾做对”的问题MCP更适合解决“Agent怎么与各种系统顺畅连接”的问题两者不是竞争关系而是可以互相嵌套的组合关系。所以在设计技能包时不用担心它和MCP重叠。MCP帮你把数据服务打通了技能包帮你在一次任务中把这些服务用对顺序、用对参数、用对输出结构。二者的组合才是我认为Agent工程化的最佳实践。最后再分享一个我个人的小体会在写技能包的过程中最花时间的往往不是写代码而是把那些“我自己凭感觉就能做好的事”用语言清晰地描述出来。比如周报这件事我心里很清楚哪些该写、哪些不值得写但要把这个判断标准变成模型能执行的规则就需要反复措辞、反复测试。这个过程一开始很痛苦但坚持下来你的技能包会越来越像你的“数字分身”——我现在的周报技能已经稳定跑了两个多月基本每周五丢一句话加一份笔记它就能产出可用的周报初稿我只用花两分钟修改措辞就收工。这种体验值得你花一晚上把第一个技能包做出来。
阅读完成 · 觉得有帮助？
