“skills”这个词最近在AI圈里的热度一直没下去过。大模型能不能从“会聊天”变成“真干活”关键就看它有没有一套好用的技能。在我自己做过几个Agent项目之后最大的体会是给模型堆提示词不如给它做技能包。这篇内容我会从我在本地构建一个技能包的完整过程讲起把Agent Skills是什么、怎么设计、怎么写代码、怎么避坑都过一遍适合正在做智能体、自动化工作流以及想把重复劳动交出去的开发者参考。1. 为什么“技能化”成了Agent落地的关键1.1 大模型是大脑但不是一双手大模型非常擅长推理、总结、生成但当它需要去操作文件系统、调用一个API、批量处理表格时直接让它“自由发挥”往往是灾难。我见过太多翻车现场模型雄心勃勃地写出了一段Python脚本结果路径拼错、编码读错、权限没配好最后还要人给它收拾残局。问题的本质在于模型擅长的是“想”而不是“稳定地执行一套动作”。就像一个人可能有很强的分析能力但如果他没练过骑车你让他骑车上路他照样会摔。人类是通过技能来固化动作的Agent也一样。所谓Agent Skills就是把那些确定性的、可重复的、步骤清晰的操作用代码和文档封装成一个能力单元让模型只需要负责“判断该用什么技能、传什么参数”具体的执行交给技能内部去完成。我在项目里做过一次很关键的方向调整最开始我会让模型自己写代码去处理文件后来发现这不仅慢、费token还不稳定。改成“把确定的步骤固化成技能模型只管调度”之后成功率从70%左右直接拉到95%以上。这个转变让我彻底认可了技能化这条路。1.2 Skill、MCP、Tool、Plugin这几个概念别再混了在讨论技能的时候很多人会把Skill和Tool、MCP、Plugin混为一谈。我一开始也踩过这个坑后来用一张对比表才彻底理清。概念定位举例特点Tool单点能力获取天气、发一封邮件一次输入一次输出简单直接Skill复合能力单元整理会议纪要把事项同步到待办包含步骤、约束、多个脚本可复用MCP标准化连接协议让Agent发现并调用某个外部数据源偏连接层解决的是通信标准问题Plugin早期扩展形态浏览器插件、IDE插件和平台强绑定跨平台复用差我的理解是Skill是“一整套手艺”Tool是“一把工具”两者是包含关系。一个技能内部可能调用多个工具也可能包含多个脚本。而MCP更像是一个插座标准任何符合这个标准的工具或数据源都能被Agent使用。所以技能实现时不一定非要绕开MCP技能完全可以作为MCP server里的一个能力端点发布。理解这层关系之后你就不会再纠结“学了Skills是不是就不用学MCP”了。实际工程里两者往往配合使用用MCP解决Agent和外部系统的连接用Skill解决特定任务的完整处理流程。1.3 什么样的任务才值得做成技能技能不是越多越好也不是任何任务都适合做成技能。我常用的判断标准总结下来有四条每周重复至少一次。如果不重复你花时间封装它成本回收不了。步骤相对稳定。来回变动的流程做成技能后维护成本会很高。输入输出边界清楚。知道输入什么、期望得到什么才好定义接口。出错之后可预测。技能失败在哪一步、报什么错都应该是可控的。不适合做技能的任务也有一个共同特征过于开放。比如“帮我写一份商业计划书”这种任务需要大量创意判断技能帮不了忙反而应该交给模型思维链去解决。我还犯过一个反面教材早期我把一个“全能办公助手”做成了技能接入口是“帮我处理任何文档”。结果SKILL.md写了上千行模型根本不知道该调用哪个脚本每次调用都靠猜。后来我把它拆成“批量转PDF”“提取合同关键信息”“汇总Excel表格”等十几个小技能效果立刻好了。经验就是一个技能只解决一件完整的小事不要试图用技能包揽一切。2. 设计一个技能包需求拆解与目录规范2.1 用“场景倒推”来划定技能边界很多人在动手写技能时直接就开始写代码这是不对的。正确做法是从使用场景倒推。我拿自己最近做的“整理下载目录”技能举例。目标场景很朴素用户下载目录里堆了一堆图片、PDF、压缩包、临时文件希望自动按照类型分类顺带把中文乱码文件名修一下最后生成一份整理报告。从这个场景能倒推出技能必须具备的几件事扫描目录、识别文件类型、生成分类规则、预览操作、执行移动、输出报告。同时也要划清楚边界。我定的边界是不删除任何文件、不处理超过2GB的目录、默认先预览后执行。这个边界非常重要因为它决定了Agent调用时能做什么、不能做什么防止模型把技能用偏。输出也必须是可感知的。用户需要看到“扫描到哪些文件、准备怎么移动、最终结果如何”。所以我的技能一定会生成一份report.md里面写明整理前后的文件清单。这不仅是给用户看的也是给Agent看的方便它向用户汇报。2.2 目录结构一个一眼能看懂的技能包技能包本质上是给Agent看的一个项目。你希望Agent每次调用前都能快速读懂你的代码结构那么目录一定要规整。我常用的结构是这样my-skill/ ├── SKILL.md ├── scripts/ │ ├── run.py │ ├── rules.py │ └── report.py ├── assets/ │ └── templates/ ├── examples/ │ └── demo.md └── tests/ ├── test_run.py └── fixtures/SKILL.md是整个技能包的说明书相当于给Agent的电梯演讲。scripts目录放真正的可执行代码。assets放模板和静态资源。examples放调用示例告诉模型什么情况下该用这个技能。tests放测试用例用来验证技能本身能不能稳定跑。这个结构不是拍脑袋定的。我试过把说明都塞进代码注释结果Agent根本不会细看注释我也试过没有tests目录改一次代码就提心吊胆。目录规整带来的最大好处是人能快速维护Agent也能通过读取SKILL.md快速建立调用预期。2.3 SKILL.md怎么写模型才能真读明白SKILL.md是整个技能设计里最容易被低估的部分。很多人以为它是给开发看的文档其实它是给模型看的关键prompt。模型读不懂SKILL.md技能写得再优雅它也不会用。我沉淀了一个比较通用的写法模板核心原则是“一屏读完、示例优先、明确边界”。--- name: organize_downloads description: 把指定目录下的文件按类型分类整理修复乱码文件名并生成整理报告。 --- 触发场景当用户要求“整理下载文件夹”“把下载目录分分类”“清理乱文件”时使用。 输入参数 - folder: 需要整理的目录路径 - dry_run: 是否只预览不实际移动默认 true 执行步骤 1. 扫描目录读取所有文件信息。 2. 根据扩展名和关键词匹配分类规则。 3. 生成整理预览不执行任何移动。 4. 若 dry_run 为 false执行移动并生成报告。 边界与禁忌 - 绝不删除任何文件。 - 不处理超过 2GB 的目录。 - 不移动 system 相关目录下的文件。 示例 用户说 “整理一下我的下载文件夹” - 调用 organize_downloads(folder/home/user/Downloads, dry_runtrue)这里最需要注意的是不要在SKILL.md里堆砌大量规则。我之前犯过毛病把技术细节、错误码、异常处理全部写进去结果模型反而抓不住重点。SKILL.md要像给实习生写的任务卡告诉他什么场景触发、怎么做、不要做什么剩下的让脚本内部接管。3. 用代码实现一个可落地的技能3.1 准备环境其实不需要重型框架技能不依赖特定框架。最朴素的实现就是Python脚本加一个标准目录属于“有手就行”的范畴。我自己一直在用Python 3.10以上版本因为新版类型语法和路径操作写起来舒服很多。准备方式很简单python3 -m venv .venv source .venv/bin/activate pip install pathspecpathspec这个库用来做文件匹配规则比我手动写通配符匹配靠谱。有些操作需要操作docx、xlsx时再加python-docx、openpyxl等库。这里我的建议是技能依赖的第三方库越少越好依赖越多Agent环境迁移和测试就越麻烦。3.2 最小可运行技能文件分类整理脚本下面是一个简化版本的核心实现。它接收目录路径和一个dry_run参数扫描文件、按规则分类、预览后再执行。我不会贴完整项目代码但这段代码足以说明技能内部是怎么组织的。import argparse import shutil from pathlib import Path def classify(file_path: Path) - str: ext file_path.suffix.lower() if ext in {.jpg, .png, .gif, .webp}: return images if ext in {.pdf, .docx, .txt, .md}: return documents if ext in {.zip, .tar, .gz}: return archives return others def scan(folder: Path): return [p for p in folder.iterdir() if p.is_file()] def organize(folder: Path, dry_run: bool True): files scan(folder) for f in files: target_dir folder / classify(f) target target_dir / f.name print(f[{DRY if dry_run else MOVE}] {f} - {target}) if not dry_run: target_dir.mkdir(exist_okTrue) shutil.move(str(f), str(target)) if __name__ __main__: parser argparse.ArgumentParser() parser.add_argument(--folder, requiredTrue) parser.add_argument(--dry-run, actionstore_true, defaultTrue) args parser.parse_args() organize(Path(args.folder), dry_runargs.dry_run)有人会觉得这个脚本太简单但真正工程化的技能本来就不需要花哨逻辑把稳定的事情做稳才是关键。真正复杂的部分往往在文件名编码处理、冲突检测、日志输出格式这些细节上。比如中文乱码文件名就需要用os.rename前先检查目标是否存在否则会覆盖文件。3.3 把技能接进Agent注册与调用脚本写完不是终点如何塞给Agent才是重点。如果你用的是Claude、OpenAI的Agent SDK这类工具最简单的方式就是把SKILL.md放到系统提示词里同时把scripts里的执行脚本注册成可调用工具。如果你的框架支持工具Schema那就按JSON Schema注册{ name: organize_downloads, description: 整理下载目录按文件类型分类并生成报告。用户提到整理下载文件夹、清理文件时调用。, parameters: { type: object, properties: { folder: { type: string, description: 待整理的目录路径 }, dry_run: { type: boolean, description: 是否只预览不移动默认true, default: true } }, required: [folder] } }这里的关键是把入参尽量压缩到3到5个。参数越多模型调用时越容易出现幻觉或者漏传。description要写得像使用意图而不是冷冰冰的字段说明因为模型会靠description判断该不该调用。我自己在调试时发现dry_run参数尤其值得保留。模型第一次调用技能时默认只会做预览用户看到预览结果后确认再触发真实执行。这相当于一个双保险能避免很多不必要的破坏性操作。3.4 本地验证让模型在没有你的时候也能工作正确技能做出来后不要急着交给Agent。我先在本地环境做一轮验证流程分三层第一层脚本自测。直接命令行跑确保脚本本身没有语法错误、路径错误、权限问题。这一步反复执行确认输出稳定。第二层用例覆盖。我会准备三个典型测试目录一个全是乱文件名一个包含嵌套子目录一个包含超大文件。跑下来记录日志确认分类规则正确、没有误移、报告生成正常。第三层模拟用户意图。写一小段Agent调用测试用不同说法表达同一个意图比如“给下载文件夹分一下类”“把Downloads整理一下”看模型是否能正确解析参数并触发技能。如果模型总是不触发问题多半出在SKILL.md的description描述上需要改成用户口语表达。[DRY] /tmp/dl/report_2023.pdf - /tmp/dl/documents/report_2023.pdf [DRY] /tmp/dl/photo_1.jpg - /tmp/dl/images/photo_1.jpg [DRY] /tmp/dl/pkg.zip - /tmp/dl/archives/pkg.zip Dry run complete: 3 files would be moved看到这样的输出技能才算基本过关。我还会加一步破坏性测试直接跑非dry-run版本然后核对目标目录文件完整性。破坏性测试不容跳过只有真正执行过一遍你才会发现哪些脚本存在覆盖文件或者重复执行的隐患。4. 实践复盘设计模式、常见坑与团队协作4.1 三种技能设计模式把技能做多之后我发现它们其实能归纳成三种模式。第一种是流程编排型。适合多步骤、确定性的流水线任务比如“发布前检查”就是lint、跑测试、打包、输出结果一整串动作。这种技能内部步骤固定模型只需要触发和传初始参数就够了。第二种是工具封装型。适合把外部API、命令行封装成Agent可调用的子程序比如“发送Slack消息”“读写Excel文件”。核心价值是让模型免去对接API细节的负担。第三种是知识检索型。适合领域问答场景比如产品FAQ查询、历史会议纪要检索。这种技能内部通常是向量检索或数据库查询把最相关的文档片段返回给模型帮助它给出有依据的回答。实际技能往往是混合的。比如“整理会议纪要”技能需要调用知识检索找到历史纪要格式再用工具封装生成待办事项最后按流程编排发送通知。但设计时一定要分清主从模式主模式决定结构其他模式作为内部组件。4.2 五个高频翻车现场与排查清单技能开发中遇到的问题远超代码本身的难度。我整理了一份高频问题清单算是比较实用的避坑手册。问题表现排查思路SKILL.md信息过载模型乱调用或总是重复同一执行步骤精简SKILL.md把规则挪到代码里说明文档只留核心流程和示例脚本不幂等重复运行时文件被二次移动、报告重复生成执行前检查目标状态已有目标文件则跳过或改名路径硬编码换机器后技能直接崩所有路径由参数注入禁止在代码里写死用户目录并发冲突多个Agent同时调用导致数据错乱技能入口加文件锁保证同一时刻只有一个实例运行权限范围过大模型能读取到不该读的目录技能运行前限定工作目录默认最小权限原则每个问题我都在真实项目里遇到过。比如幂等问题最初我的技能每次都会重新生成报告两次跑完report.md被覆盖用户以为出错了。后来我改成如果报告已经存在先归档再加时间戳。排查这类问题我有个“三问自查法”脚本单独跑能不能成功重复跑结果是否一致不给模型额外提示它能不能完成任务三问都通过技能才叫合格。4.3 版本管理与团队复用技能做到一定数量后管理和复用就成了新问题。我目前的习惯是用git管理每个技能包单独建仓库按语义化版本标注改动。每次改SKILL.md或者脚本都会在README里写清楚变更内容方便回溯。团队内如果有多个Agent项目我还会维护一个技能索引表记录每个技能的路径、版本、适用场景和维护人。这样其他项目要复用的时候不用一遍遍问我自己去看索引就能找到合适技能。技能上架前的评审清单我也有一个简化版边界是否清晰、是否有dry-run或预览模式、是否有测试用例、是否硬编码了路径、是否包含密钥。没问题才同步到团队私有仓库。关于密钥这里多说一句。技能包很多时候需要调用API比如发消息、写日历。千万不要把API Key写在脚本或配置里。放在环境变量或独立的secret文件中并加入.gitignore。我见过不止一次技能仓库被公开后密钥泄露的情况这属于底线问题绝对不能犯。做技能做到现在我最大的体会是不要低估确定性步骤的价值也不要高估模型自由发挥的稳定性。真正好用的Agent不是什么都让模型自己来而是让模型做好判断和调度把重复、繁琐、高风险的操作交给技能去完成。如果你也想尝试建议从自己每周重复三次以上的小任务开始拆出输入、输出、边界做成一个最小技能包跑通之后你会立刻感受到这套方法的价值。