1. 从“skills”这个热词说起它到底是什么最近几个月不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。有人问“skills推荐”有人搜“skills大全”还有人半夜在群里喊“今天学会了skills打开新世界”。如果你只是偶尔刷到可能会以为这是某个新出的前端框架或者某个游戏技能系统。但稍微深入一点就会发现大家讨论的“skills”其实是一个更具体的东西——Agent Skills也就是给AI智能体Agent用的技能包。简单来说Agent Skills就是一套预定义好的指令集、工具调用逻辑和上下文模板它让AI Agent在特定场景下能稳定地完成某类任务。比如你有一个负责写论文的Agent你可以给它装一个“论文写作skill”里面包含了文献检索的流程、引用格式的规范、段落结构的模板你有一个负责前端开发的Agent你可以给它装一个“前端开发skill”里面包含了组件库的用法、样式规范、构建工具的配置。这些skill不是代码库也不是插件而是一种结构化的能力描述通常以Markdown文件或JSON配置的形式存在Agent在运行时读取这些描述然后按照里面的逻辑去执行。为什么这个东西突然火了因为大家发现光有一个强大的模型还不够模型再聪明如果没有明确的“操作手册”它在具体任务上还是会跑偏。就像你招了一个名校毕业的高材生他智商很高但你如果不告诉他公司的代码规范、部署流程、测试要求他写出来的代码照样没法直接用。Agent Skills就是这份“操作手册”它把领域知识、操作步骤、注意事项打包成一个可复用的模块让Agent在不同项目之间快速切换角色。目前围绕skills的生态已经初步成型。有官方市场比如Google Cloud和GKE相关的Agent Skills也有社区驱动的skills下载平台还有人在GitHub上开源自己的skills集合。工具链方面npx成了安装和运行skills的常见入口比如npx playwright install这种命令虽然偶尔会失败但整体上已经成了开发者习惯的操作方式。Claude的Agent Skills和MCP Servers的结合也是热门话题有人写了“a first principles deep dive”来分析底层逻辑也有人整理“codex好用的skills”清单。甚至出现了“自动挖洞skills”这种偏安全测试方向的玩法以及“分镜skills下载”这种偏内容创作的应用。这篇文章不打算给你一个“skills大全”的列表那种东西网上已经够多了。我想做的是从一个实际使用者的角度把skills的选型逻辑、安装配置、开发方法、常见坑点讲清楚。不管你是刚听说这个词的新手还是已经装过几个skills但总觉得哪里不对的老手都能从这里找到可以直接抄作业的步骤和避坑经验。2. 核心思路拆解为什么是Skills而不是别的方案2.1 从Prompt Engineering到Skill Engineering的演进逻辑最早大家用AI Agent的时候习惯把所有指令都塞进一个巨大的system prompt里。比如你要做一个代码审查Agent你会在prompt里写“你是一个资深代码审查员请检查以下代码的风格、安全漏洞、性能问题……”然后每次调用都带上这一大段文字。这种做法在任务单一的时候没问题但一旦任务变多prompt就会膨胀到几千甚至上万token不仅浪费上下文窗口而且模型在长prompt里容易“迷失”忽略掉后面的指令。后来有人尝试用few-shot examples给几个输入输出的例子让模型模仿。这比纯文字描述好一些但例子多了同样占地方而且例子覆盖不到所有边界情况。再后来出现了function calling和tool use模型可以调用外部工具了但工具本身只是能力怎么组合这些工具、在什么场景下调用哪个工具还是需要一套逻辑来管理。Agent Skills的出现本质上是对这个问题的工程化回答。它把“指令工具上下文示例”打包成一个独立的、可版本控制的、可组合的模块。你可以把它理解成给Agent用的“npm包”——需要什么能力就装什么skill不需要的时候就卸载不同项目之间可以复用同一套skill也可以根据项目特点覆盖部分配置。这种模块化的思路比把所有东西塞进一个prompt要清晰得多也更容易维护。2.2 Skills与MCP Servers的关系互补而非替代很多人第一次接触skills的时候会问这和MCP Servers有什么区别是不是有了MCP就不需要skills了其实两者解决的是不同层面的问题。MCPModel Context ProtocolServers解决的是“模型怎么和外部系统通信”的问题。比如你的Agent需要读取本地文件、查询数据库、调用某个APIMCP Server提供了标准化的接口让模型能安全地发起这些请求。它关注的是连接和协议。Skills解决的是“模型在特定场景下应该怎么做”的问题。比如同样是调用数据库在“用户查询订单”的场景下应该先验证用户身份再查订单表最后格式化输出在“管理员导出报表”的场景下应该先检查权限再批量查询最后生成CSV文件。这些流程性的知识MCP Server本身不关心它只负责把请求发出去。Skills就是把这些流程固化下来让Agent知道在什么情况下走什么路径。所以一个完整的Agent系统往往是MCP Servers提供底层能力Skills提供上层逻辑。两者配合使用而不是二选一。在实际项目中我通常先把需要的MCP Server配好确保Agent能访问到必要的资源然后再根据具体任务写对应的skill把操作流程和注意事项写进去。这样Agent既有“手”去执行又有“脑子”去判断。2.3 为什么npx成了Skills生态的默认入口如果你去看现在流行的skills安装方式会发现npx出现的频率极高。比如npx playwright install、npx some-org/skill-name之类的命令。为什么是npx而不是pip、brew或者直接下载压缩包npx是Node.js生态里的包执行工具它的特点是“即用即走”——不需要全局安装直接运行包里的可执行文件。对于skills来说这有几个好处。第一skills的更新频率很高今天装的版本明天可能就过时了npx每次运行都会检查最新版本省去了手动更新的麻烦。第二skills往往依赖特定的运行时环境比如Playwright需要浏览器二进制文件npx能自动处理这些依赖的下载和配置。第三npx的跨平台一致性比较好Windows、macOS、Linux上的行为基本一致减少了“在我机器上能跑”的问题。当然npx也不是没有缺点。最典型的就是网络问题导致的安装失败比如npx playwright install在国内网络环境下经常卡住或者报错。这个后面会专门讲排查方法。另外npx每次运行都要下载包如果网络不好启动速度会很慢。对于频繁使用的skill可以考虑全局安装或者用本地缓存来加速。2.4 选型时容易踩的认知误区在帮别人排查skills相关问题时我发现几个反复出现的认知误区。第一个是“skill越多越好”。有人一口气装了十几个skills结果Agent在运行时不知道该用哪个或者不同skill之间的指令互相冲突。比如一个skill说“输出要简洁”另一个skill说“输出要详细”Agent就懵了。我的建议是按项目装skill一个项目里同时激活的skill不要超过五个而且要有明确的主次关系。第二个误区是“skill写一次就能一直用”。实际上skill是需要迭代的。你在项目初期写的skill随着项目发展可能有些步骤已经过时了有些边界情况没考虑到。我习惯每隔两周回顾一下正在使用的skill看看有没有需要更新的地方。特别是当Agent在某类任务上反复出错时往往不是模型的问题而是skill里的指令不够明确。第三个误区是“skill可以完全替代人工判断”。有些团队把skill写得很死每一步都规定得死死的结果Agent遇到稍微不同的情况就不知道怎么处理了。好的skill应该是指南而不是枷锁。它告诉Agent“通常这样做”但也留出空间让Agent根据实际情况调整。比如在代码审查skill里我会写“优先检查安全漏洞其次是性能问题最后是代码风格”而不是“必须按这个顺序检查不得跳过任何一项”。3. 核心细节解析一个Skill的完整结构3.1 Skill文件的典型组成要素一个标准的Agent Skill通常包含几个核心部分。首先是元信息包括skill的名称、版本、作者、适用场景描述。这部分看起来简单但很重要因为Agent在决定是否使用某个skill时首先看的就是元信息里的场景描述。如果描述写得太模糊比如“用于处理数据”Agent就不知道什么时候该用它。好的描述应该具体到任务类型比如“用于将CSV文件转换为JSON格式包含字段映射和类型转换”。第二部分是指令集也就是skill的核心逻辑。这部分通常用自然语言写成但需要非常精确。比如“读取输入文件”这种指令就太模糊了应该写成“读取当前工作目录下的input.csv文件如果文件不存在则报错并终止”。指令集里还要包含条件分支比如“如果字段A的值大于100则执行X操作否则执行Y操作”。这些分支逻辑是skill区别于普通prompt的关键它让Agent能根据输入动态调整行为。第三部分是工具声明列出这个skill需要用到哪些外部工具或MCP Server。比如一个网页抓取的skill可能需要声明它依赖Playwright MCP Server。这样在加载skill时系统可以自动检查依赖是否满足避免运行时才发现工具缺失。第四部分是示例给出几个典型的输入输出对。示例不需要多两三个就够但要覆盖主要场景和边界情况。示例的作用是让Agent更准确地理解指令的意图特别是在指令本身有歧义的时候示例能起到“锚定”的作用。第五部分是注意事项列出这个skill在使用中容易出错的地方。比如“不要对超过1GB的文件使用此skill会导致内存溢出”或者“如果API返回429状态码等待5秒后重试最多重试3次”。这部分往往是经验积累的结果新手写的skill通常缺少这一块导致Agent在遇到异常时不知道怎么处理。3.2 指令编写的颗粒度控制写skill指令时最难的把握颗粒度。写得太粗Agent自由发挥的空间太大结果不稳定写得太细Agent变成了只会按固定流程执行的机器人遇到新情况就卡住。我的经验是核心流程要细边缘情况要粗。比如一个“发送邮件”的skill核心流程应该写清楚验证收件人地址格式、检查附件大小、选择邮件模板、调用发送接口、记录发送日志。这些步骤每一步都不能少而且要明确顺序。但边缘情况可以写得灵活一些比如“如果发送失败根据错误码决定是重试还是通知用户”不需要把每种错误码对应的操作都列出来让Agent根据常识判断即可。另一个技巧是用“必须”和“建议”来区分优先级。必须做的事情用“必须”开头比如“必须在发送前验证收件人地址”。建议做的事情用“建议”开头比如“建议在邮件正文开头加上称呼”。这样Agent在资源有限或者时间紧迫时知道哪些可以妥协哪些不能。还有一个容易忽略的点是指令的否定形式。很多人写skill时只写“要做什么”不写“不要做什么”。但实际使用中Agent经常会做一些你不想让它做的事情。比如你写了一个“总结文档”的skillAgent可能会在总结里加入自己的评论这时候就需要明确写“不要添加原文中没有的观点”。否定指令往往比肯定指令更能约束Agent的行为。3.3 上下文窗口管理与Skill的加载策略Agent的上下文窗口是有限的而skill文件本身会占用一部分。如果一个skill写得太长比如超过5000字那加载它之后剩下的空间就不多了Agent处理实际任务时可能不够用。所以skill的篇幅需要控制。我的做法是把skill分成核心层和扩展层。核心层是必须加载的包含最基本的指令和工具声明通常控制在1000字以内。扩展层是可选加载的包含详细的示例、边缘情况处理、参考资料等只有在需要的时候才加载。这样Agent在大多数情况下只需要加载核心层节省上下文空间。另外多个skill同时加载时要注意它们之间的顺序。一般来说越具体的skill应该越靠后加载这样它的指令会覆盖前面更通用的skill。比如你有一个通用的“代码编写”skill和一个具体的“React组件编写”skill应该先加载通用的再加载具体的这样React相关的特殊要求会优先生效。还有一个技巧是用引用代替复制。如果两个skill都需要用到同一段工具说明不要在每个skill里都复制一遍而是把这段说明放在一个公共文件里skill里用引用链接指向它。这样既节省空间又方便统一更新。3.4 版本管理与团队协作中的Skill治理当团队里多个人都在写skill时版本管理就成了问题。我见过最混乱的情况是同一个skill在不同人的机器上有不同的版本导致Agent的行为不一致排查问题时非常头疼。解决这个问题的第一步是把skill纳入版本控制。不管是Git还是其他工具skill文件应该和代码一样被管理起来。每次修改都要有commit记录说明改了什么、为什么改。这样当Agent行为发生变化时可以快速定位到是哪次修改导致的。第二步是建立skill的评审机制。新skill或者对现有skill的重大修改应该经过至少一个人的review。Review的重点不是代码风格而是指令的清晰度、边界情况的覆盖、以及是否与其他skill冲突。我通常会让review的人模拟几个场景看看按照skill的指令走下来结果是否符合预期。第三步是定期清理废弃的skill。项目迭代过程中有些skill可能已经不再使用了但还留在仓库里。这些废弃的skill不仅占地方还可能被误加载。我习惯每个季度做一次skill盘点把过去三个月没有使用记录的skill标记为“待废弃”再过一个月还没有使用就删除。第四步是文档化skill的依赖关系。有些skill依赖于特定的MCP Server或者环境变量这些依赖应该在文档里写清楚。新成员加入时按照文档配置环境就能避免“为什么我的Agent跑不起来”这类问题。4. 实操过程从零安装并运行一个Skill4.1 环境准备与npx的配置要点在开始安装skill之前需要确保基础环境就绪。最核心的是Node.js和npm因为大多数skill的安装和运行都依赖npx。Node.js的版本建议用LTS版本比如18.x或20.x太新的版本可能有些包还没适配太旧的版本可能缺少某些API。安装Node.js的方式有很多我推荐用nvmNode Version Manager来管理这样可以在不同项目之间切换Node版本。在macOS或Linux上可以用curl安装nvm然后nvm install 20。在Windows上可以用nvm-windows安装过程稍微麻烦一点但用起来和macOS差不多。装好Node.js之后检查一下npm的registry配置。默认的registry在国内访问可能比较慢可以换成国内的镜像源。命令是npm config set registry https://registry.npmmirror.com。这个操作能显著提升npx下载包的速度减少超时失败的概率。还有一个容易忽略的配置是npx的缓存目录。默认情况下npx会把下载的包缓存在用户目录下的.npm/_npx文件夹里。如果这个文件夹所在的分区空间不足会导致安装失败。可以通过npm config set cache /path/to/larger/disk来修改缓存位置。我一般会把它设在一个空间充足的盘上避免因为磁盘满导致的各种奇怪报错。4.2 安装一个Skill的完整命令与参数说明假设我们要安装一个用于网页自动化的skill它依赖Playwright。典型的安装命令是npx playwright install。这个命令会下载Playwright的浏览器二进制文件包括Chromium、Firefox和WebKit。如果只需要Chromium可以用npx playwright install chromium来节省下载时间和磁盘空间。执行这个命令时npx会先检查本地是否有Playwright包如果没有就从registry下载。下载完成后它会根据当前操作系统下载对应的浏览器二进制文件。在Linux上可能还需要安装一些系统依赖比如libnss3、libatk-bridge2.0-0等。Playwright提供了一个命令npx playwright install-deps来自动安装这些依赖但在某些Linux发行版上可能需要sudo权限。安装完成后可以用npx playwright --version来验证是否成功。如果输出了版本号说明安装没问题。接下来就可以在skill文件里引用Playwright了。通常skill文件里会写类似“使用Playwright打开网页等待页面加载完成然后提取指定元素的内容”这样的指令。对于其他类型的skill安装方式可能略有不同。有些skill是纯指令文件不需要额外的二进制依赖直接下载Markdown文件放到指定目录即可。有些skill需要通过npm包的形式安装比如npx org/skill-name install。具体命令要看skill的文档但核心逻辑是一样的先确保运行时环境就绪再下载skill本身最后验证安装结果。4.3 配置Skill的加载路径与优先级安装完skill之后需要告诉Agent去哪里加载它。不同的Agent框架有不同的配置方式但通常都会有一个配置文件或者环境变量来指定skill的搜索路径。以常见的做法为例可以在项目根目录下创建一个.skills文件夹把下载的skill文件放进去。然后在Agent的配置文件里写上skills_path: ./.skills。这样Agent启动时会自动扫描这个文件夹加载里面所有的skill。如果同时有多个skill目录比如一个全局的skill目录和一个项目级的skill目录需要配置优先级。一般来说项目级的skill应该优先于全局的skill因为项目级的更具体。配置方式可能是skills_path: [./.skills, ~/.global-skills]Agent会按顺序加载后面的覆盖前面的同名skill。还有一个细节是skill的启用和禁用。有些skill可能只在特定任务中需要平时不想让它占用上下文。可以在配置文件里加一个enabled_skills列表只列出当前项目需要的skill。或者用disabled_skills列表来排除不想用的skill。我通常用白名单的方式只启用明确需要的skill避免意外加载了不相关的skill导致行为异常。4.4 验证Skill是否生效的三种方法装好skill之后怎么确认它真的生效了我常用三种方法。第一种是直接询问Agent。比如问它“你现在有哪些可用的skill”如果Agent能列出你刚装的skill名称和描述说明加载成功了。这个方法最简单但只能验证skill被识别了不能验证skill的逻辑是否正确执行。第二种是构造一个测试任务。比如你装了一个“JSON格式化”的skill就给它一个格式混乱的JSON字符串看它是否能按照skill里定义的规则输出格式化后的结果。这个方法能验证skill的核心逻辑但需要你设计好测试用例。第三种是查看日志。大多数Agent框架在加载skill时会输出日志显示加载了哪些文件、是否有解析错误、是否有依赖缺失。如果日志里有warning或error就需要进一步排查。我习惯在第一次安装skill后把日志级别调到debug仔细看一遍加载过程确认没有隐藏的问题。三种方法结合使用基本能覆盖大多数情况。如果三种方法都通过了但实际使用时还是有问题那可能是skill的指令本身有歧义需要回去修改skill文件。5. 常见问题与排查技巧实录5.1 npx playwright install失败的各种原因与对策npx playwright install失败是最高频的问题之一。根据我帮别人排查的经验原因可以分成几类。第一类是网络问题。表现是命令卡在“Downloading”阶段或者报错“ETIMEDOUT”。对策是换用国内镜像源或者设置代理环境变量。Playwright支持通过PLAYWRIGHT_DOWNLOAD_HOST环境变量来指定下载源。比如export PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright然后再执行安装命令。这个镜像源同步了Playwright的浏览器二进制文件下载速度会快很多。第二类是权限问题。在Linux上如果npm的全局目录需要sudo权限而你没有用sudo就会报“EACCES”错误。对策是修改npm的默认目录到用户有权限的位置命令是npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到PATH里。这样以后安装全局包就不需要sudo了。第三类是磁盘空间不足。Playwright的三个浏览器加起来大概1GB左右如果磁盘剩余空间不够安装会中途失败。对策是清理磁盘或者只安装需要的浏览器比如npx playwright install chromium。另外可以把Playwright的缓存目录设到空间大的分区通过PLAYWRIGHT_BROWSERS_PATH环境变量来指定。第四类是系统依赖缺失。在Linux上Playwright的浏览器需要一些系统库比如libnss3、libatk1.0-0等。如果这些库没装浏览器启动时会报错。对策是运行npx playwright install-deps它会自动安装所需的系统依赖。如果这个命令也失败可以手动用包管理器安装比如在Ubuntu上sudo apt-get install libnss3 libatk1.0-0 libatk-bridge2.0-0。第五类是Node.js版本不兼容。有些Playwright版本要求Node.js 16以上如果你的Node.js太旧会报语法错误或者API不存在的错误。对策是升级Node.js到LTS版本。5.2 Skill加载后Agent行为不符合预期的排查思路有时候skill装好了日志也显示加载成功但Agent的行为就是不对。比如skill里写了“输出用JSON格式”但Agent还是输出Markdown。这种情况通常不是安装问题而是skill的指令没有被正确理解。排查的第一步是检查skill的优先级。如果同时加载了多个skill后面的skill可能会覆盖前面的。比如你有一个通用的“输出格式”skill说用Markdown又有一个具体的“API响应”skill说用JSON如果加载顺序不对可能通用的覆盖了具体的。解决方法是调整加载顺序把更具体的skill放在后面。第二步是检查指令的明确性。有些指令写得太模糊Agent可能理解成别的意思。比如“输出简洁”这种指令不同模型对“简洁”的理解不一样。可以改成“输出不超过三句话每句话不超过20个字”。越具体的指令执行结果越稳定。第三步是检查是否有冲突的指令。如果两个skill里都有关于输出格式的指令而且互相矛盾Agent可能会随机选一个执行。解决方法是合并这两个skill或者在一个skill里明确写“如果同时满足A和B条件优先执行A”。第四步是用示例来锚定行为。如果指令本身没问题但Agent还是跑偏可以在skill里加一两个示例明确展示期望的输入输出。示例对Agent的影响很大有时候比指令本身还管用。5.3 常见问题速查表问题现象可能原因排查方法解决方案npx命令卡住不动网络超时检查网络连接尝试ping registry换国内镜像源或设置下载主机环境变量报错EACCES权限不足检查npm全局目录权限修改npm prefix到用户目录或使用sudo浏览器启动失败系统依赖缺失查看错误日志中的缺失库名运行install-deps或手动安装系统库Agent不执行skill指令skill未加载或优先级低询问Agent可用的skill列表检查加载路径和顺序调整优先级Agent执行结果不稳定指令模糊或有冲突对比不同输入下的输出差异细化指令消除冲突增加示例skill加载报解析错误文件格式不正确查看日志中的具体错误行检查Markdown或JSON格式确保符合规范上下文窗口不足skill太长查看token使用量拆分skill为核心层和扩展层按需加载5.4 几个只有踩过坑才知道的细节第一个细节是skill文件的编码问题。如果skill文件里包含中文一定要确保文件是UTF-8编码。有些编辑器默认用GBK保存导致Agent读取时出现乱码指令就失效了。我习惯在文件开头加一个BOM标记或者在项目配置里强制指定编码。第二个细节是skill名称的大小写敏感。在Linux上文件名是大小写敏感的MySkill.md和myskill.md是两个不同的文件。如果配置里写的是小写但实际文件名是大写就会加载失败。建议统一用小写字母加连字符来命名skill文件避免这个问题。第三个细节是skill的依赖声明要完整。有些skill依赖特定的环境变量比如API密钥。如果skill文件里没有声明这个依赖Agent在运行时才发现缺少环境变量就会报错。好的做法是在skill的元信息里加上requires: [API_KEY]这样的声明加载时就能检查出来。第四个细节是skill的更新不会自动生效。如果你修改了skill文件但Agent还在用旧版本可能是因为Agent缓存了skill内容。大多数框架需要重启Agent或者执行一个reload命令才能加载新版本。我习惯在修改skill后先重启Agent再验证行为是否变化。第五个细节是多个skill之间的工具冲突。如果两个skill都声明需要Playwright但版本要求不同可能会导致其中一个无法正常工作。解决方法是统一工具版本或者在skill里明确指定兼容的版本范围。6. 进阶玩法自己写一个Skill并发布6.1 从需求到Skill的转化方法写skill的第一步不是打开编辑器而是想清楚这个skill要解决什么问题。我通常会用一句话描述需求比如“我需要一个skill能把会议记录整理成待办事项列表”。然后把这个需求拆解成几个步骤读取会议记录、识别其中的行动项、提取负责人和截止日期、格式化成待办列表、输出结果。拆解完之后针对每个步骤问自己几个问题这一步的输入是什么输出是什么有没有边界情况比如“识别行动项”这一步输入是一段文字输出是行动项列表。边界情况包括有些行动项没有明确的负责人有些没有截止日期有些是多人负责。这些边界情况需要在skill里写清楚怎么处理。然后考虑需要哪些工具。如果会议记录是文本文件可能只需要文件读取工具。如果是音频文件就需要语音转文字的工具。如果是网页上的会议记录就需要网页抓取工具。把这些工具列出来在skill的元信息里声明。最后是写指令。指令要按步骤写每一步都写清楚输入、操作、输出。对于边界情况用条件分支来处理。比如“如果行动项没有负责人标记为‘待分配’如果没有截止日期标记为‘待定’”。写完之后自己读一遍看看有没有歧义的地方。6.2 Skill文件的编写规范与模板一个可复用的skill模板大概长这样--- name: meeting-to-todo version: 1.0.0 description: 将会议记录整理成待办事项列表 requires: - file-reader - text-analyzer --- # 会议记录转待办事项 ## 指令 1. 读取当前工作目录下的meeting-notes.txt文件。 2. 分析文本识别所有以“行动项”、“待办”、“TODO”开头的段落。 3. 对每个行动项提取以下字段 - 任务描述行动项的主要内容 - 负责人如果文本中有“某人”或“由某人负责”提取该人名 - 截止日期如果文本中有日期格式提取该日期 4. 如果行动项缺少负责人标记为“待分配”。 5. 如果行动项缺少截止日期标记为“待定”。 6. 将所有行动项按截止日期排序日期近的在前。 7. 输出格式为Markdown表格包含任务描述、负责人、截止日期三列。 ## 示例 输入 行动项完成项目提案由张三负责截止日期2024-06-01。 待办联系供应商确认报价。 输出 | 任务描述 | 负责人 | 截止日期 | |---------|--------|---------| | 完成项目提案 | 张三 | 2024-06-01 | | 联系供应商确认报价 | 待分配 | 待定 | ## 注意事项 - 不要修改行动项的原始描述只做提取和格式化。 - 如果文本中没有找到任何行动项输出“未发现行动项”。 - 日期格式统一为YYYY-MM-DD。这个模板包含了元信息、指令、示例、注意事项四个部分。指令部分用有序列表每一步都很明确。示例部分给出了一个完整的输入输出对。注意事项部分列出了容易出错的地方。6.3 测试与迭代如何验证Skill的鲁棒性写完skill之后不能直接投入使用要先测试。我通常准备三组测试数据一组是正常情况一组是边界情况一组是异常情况。正常情况就是典型的输入比如上面例子中有一个完整的行动项。边界情况包括没有负责人的行动项、没有截止日期的行动项、日期格式不标准的行动项、多个行动项混在一起。异常情况包括文件不存在、文件为空、文件内容不是会议记录。对每组数据运行Agent并检查输出。如果输出符合预期就通过。如果不符合分析是skill指令的问题还是Agent理解的问题。如果是指令的问题修改指令如果是Agent理解的问题增加示例或者细化指令。测试通过后不要急着发布。先在自己的项目里用一周看看实际使用中还有没有没考虑到的情况。我经常在用了几天之后发现有些边界情况在测试时没想到但在实际使用中出现了。这时候就回去补充skill然后重新测试。6.4 发布与分享让更多人用上你的Skill如果你觉得自己的skill对别人也有用可以分享出去。分享的方式有几种。最简单的是把skill文件放到GitHub仓库里写一个README说明怎么安装和使用。如果skill比较通用可以发布到npm上让别人通过npx your-skill-name来安装。发布到npm的步骤是先在npm官网注册账号然后在项目目录下运行npm login登录再运行npm publish发布。发布之前要确保package.json里的name是唯一的version是新的。如果skill依赖其他包要在dependencies里声明。发布之后可以在技术社区里分享一下比如写一篇博客介绍这个skill解决了什么问题、怎么使用、有什么注意事项。也可以在其他人的skill基础上做改进然后提交pull request。开源社区的反馈往往能帮你发现没想到的问题也能让skill变得更完善。7. 我个人的一些使用体会用了几个月的Agent Skills最大的感受是它确实改变了我和AI协作的方式。以前我写prompt是“一次性”的每次都要重新描述需求。现在我把常用的流程写成skill需要的时候直接加载省去了大量重复描述的时间。而且skill是可以积累的今天写一个“代码审查”skill明天写一个“文档生成”skill慢慢地就形成了一套自己的工具库。另一个体会是skill的质量比数量重要得多。我见过有人收集了几十个skill但真正用的就那么几个。与其追求“skills大全”不如把常用的几个skill打磨好。一个好的skill应该是越用越顺手的每次遇到新情况就补充进去慢慢就变成了这个领域的“操作手册”。还有一个坑是不要过度依赖skill。有些任务其实用普通的prompt就能完成没必要非得写个skill。skill适合那些重复性高、流程固定、容易出错的任务。如果任务本身很灵活每次都不一样那写skill反而是一种负担。最后想说的是skills生态还在快速变化中。今天好用的工具明天可能就被替代了今天的最佳实践明天可能就过时了。保持学习的心态多试试新东西但也不要盲目追新。找到适合自己的工作流比什么都重要。
Agent Skills实战指南：从选型安装到开发避坑
1. 从“skills”这个热词说起它到底是什么最近几个月不管是在技术社区还是开发者群聊里“skills”这个词出现的频率高得离谱。有人问“skills推荐”有人搜“skills大全”还有人半夜在群里喊“今天学会了skills打开新世界”。如果你只是偶尔刷到可能会以为这是某个新出的前端框架或者某个游戏技能系统。但稍微深入一点就会发现大家讨论的“skills”其实是一个更具体的东西——Agent Skills也就是给AI智能体Agent用的技能包。简单来说Agent Skills就是一套预定义好的指令集、工具调用逻辑和上下文模板它让AI Agent在特定场景下能稳定地完成某类任务。比如你有一个负责写论文的Agent你可以给它装一个“论文写作skill”里面包含了文献检索的流程、引用格式的规范、段落结构的模板你有一个负责前端开发的Agent你可以给它装一个“前端开发skill”里面包含了组件库的用法、样式规范、构建工具的配置。这些skill不是代码库也不是插件而是一种结构化的能力描述通常以Markdown文件或JSON配置的形式存在Agent在运行时读取这些描述然后按照里面的逻辑去执行。为什么这个东西突然火了因为大家发现光有一个强大的模型还不够模型再聪明如果没有明确的“操作手册”它在具体任务上还是会跑偏。就像你招了一个名校毕业的高材生他智商很高但你如果不告诉他公司的代码规范、部署流程、测试要求他写出来的代码照样没法直接用。Agent Skills就是这份“操作手册”它把领域知识、操作步骤、注意事项打包成一个可复用的模块让Agent在不同项目之间快速切换角色。目前围绕skills的生态已经初步成型。有官方市场比如Google Cloud和GKE相关的Agent Skills也有社区驱动的skills下载平台还有人在GitHub上开源自己的skills集合。工具链方面npx成了安装和运行skills的常见入口比如npx playwright install这种命令虽然偶尔会失败但整体上已经成了开发者习惯的操作方式。Claude的Agent Skills和MCP Servers的结合也是热门话题有人写了“a first principles deep dive”来分析底层逻辑也有人整理“codex好用的skills”清单。甚至出现了“自动挖洞skills”这种偏安全测试方向的玩法以及“分镜skills下载”这种偏内容创作的应用。这篇文章不打算给你一个“skills大全”的列表那种东西网上已经够多了。我想做的是从一个实际使用者的角度把skills的选型逻辑、安装配置、开发方法、常见坑点讲清楚。不管你是刚听说这个词的新手还是已经装过几个skills但总觉得哪里不对的老手都能从这里找到可以直接抄作业的步骤和避坑经验。2. 核心思路拆解为什么是Skills而不是别的方案2.1 从Prompt Engineering到Skill Engineering的演进逻辑最早大家用AI Agent的时候习惯把所有指令都塞进一个巨大的system prompt里。比如你要做一个代码审查Agent你会在prompt里写“你是一个资深代码审查员请检查以下代码的风格、安全漏洞、性能问题……”然后每次调用都带上这一大段文字。这种做法在任务单一的时候没问题但一旦任务变多prompt就会膨胀到几千甚至上万token不仅浪费上下文窗口而且模型在长prompt里容易“迷失”忽略掉后面的指令。后来有人尝试用few-shot examples给几个输入输出的例子让模型模仿。这比纯文字描述好一些但例子多了同样占地方而且例子覆盖不到所有边界情况。再后来出现了function calling和tool use模型可以调用外部工具了但工具本身只是能力怎么组合这些工具、在什么场景下调用哪个工具还是需要一套逻辑来管理。Agent Skills的出现本质上是对这个问题的工程化回答。它把“指令工具上下文示例”打包成一个独立的、可版本控制的、可组合的模块。你可以把它理解成给Agent用的“npm包”——需要什么能力就装什么skill不需要的时候就卸载不同项目之间可以复用同一套skill也可以根据项目特点覆盖部分配置。这种模块化的思路比把所有东西塞进一个prompt要清晰得多也更容易维护。2.2 Skills与MCP Servers的关系互补而非替代很多人第一次接触skills的时候会问这和MCP Servers有什么区别是不是有了MCP就不需要skills了其实两者解决的是不同层面的问题。MCPModel Context ProtocolServers解决的是“模型怎么和外部系统通信”的问题。比如你的Agent需要读取本地文件、查询数据库、调用某个APIMCP Server提供了标准化的接口让模型能安全地发起这些请求。它关注的是连接和协议。Skills解决的是“模型在特定场景下应该怎么做”的问题。比如同样是调用数据库在“用户查询订单”的场景下应该先验证用户身份再查订单表最后格式化输出在“管理员导出报表”的场景下应该先检查权限再批量查询最后生成CSV文件。这些流程性的知识MCP Server本身不关心它只负责把请求发出去。Skills就是把这些流程固化下来让Agent知道在什么情况下走什么路径。所以一个完整的Agent系统往往是MCP Servers提供底层能力Skills提供上层逻辑。两者配合使用而不是二选一。在实际项目中我通常先把需要的MCP Server配好确保Agent能访问到必要的资源然后再根据具体任务写对应的skill把操作流程和注意事项写进去。这样Agent既有“手”去执行又有“脑子”去判断。2.3 为什么npx成了Skills生态的默认入口如果你去看现在流行的skills安装方式会发现npx出现的频率极高。比如npx playwright install、npx some-org/skill-name之类的命令。为什么是npx而不是pip、brew或者直接下载压缩包npx是Node.js生态里的包执行工具它的特点是“即用即走”——不需要全局安装直接运行包里的可执行文件。对于skills来说这有几个好处。第一skills的更新频率很高今天装的版本明天可能就过时了npx每次运行都会检查最新版本省去了手动更新的麻烦。第二skills往往依赖特定的运行时环境比如Playwright需要浏览器二进制文件npx能自动处理这些依赖的下载和配置。第三npx的跨平台一致性比较好Windows、macOS、Linux上的行为基本一致减少了“在我机器上能跑”的问题。当然npx也不是没有缺点。最典型的就是网络问题导致的安装失败比如npx playwright install在国内网络环境下经常卡住或者报错。这个后面会专门讲排查方法。另外npx每次运行都要下载包如果网络不好启动速度会很慢。对于频繁使用的skill可以考虑全局安装或者用本地缓存来加速。2.4 选型时容易踩的认知误区在帮别人排查skills相关问题时我发现几个反复出现的认知误区。第一个是“skill越多越好”。有人一口气装了十几个skills结果Agent在运行时不知道该用哪个或者不同skill之间的指令互相冲突。比如一个skill说“输出要简洁”另一个skill说“输出要详细”Agent就懵了。我的建议是按项目装skill一个项目里同时激活的skill不要超过五个而且要有明确的主次关系。第二个误区是“skill写一次就能一直用”。实际上skill是需要迭代的。你在项目初期写的skill随着项目发展可能有些步骤已经过时了有些边界情况没考虑到。我习惯每隔两周回顾一下正在使用的skill看看有没有需要更新的地方。特别是当Agent在某类任务上反复出错时往往不是模型的问题而是skill里的指令不够明确。第三个误区是“skill可以完全替代人工判断”。有些团队把skill写得很死每一步都规定得死死的结果Agent遇到稍微不同的情况就不知道怎么处理了。好的skill应该是指南而不是枷锁。它告诉Agent“通常这样做”但也留出空间让Agent根据实际情况调整。比如在代码审查skill里我会写“优先检查安全漏洞其次是性能问题最后是代码风格”而不是“必须按这个顺序检查不得跳过任何一项”。3. 核心细节解析一个Skill的完整结构3.1 Skill文件的典型组成要素一个标准的Agent Skill通常包含几个核心部分。首先是元信息包括skill的名称、版本、作者、适用场景描述。这部分看起来简单但很重要因为Agent在决定是否使用某个skill时首先看的就是元信息里的场景描述。如果描述写得太模糊比如“用于处理数据”Agent就不知道什么时候该用它。好的描述应该具体到任务类型比如“用于将CSV文件转换为JSON格式包含字段映射和类型转换”。第二部分是指令集也就是skill的核心逻辑。这部分通常用自然语言写成但需要非常精确。比如“读取输入文件”这种指令就太模糊了应该写成“读取当前工作目录下的input.csv文件如果文件不存在则报错并终止”。指令集里还要包含条件分支比如“如果字段A的值大于100则执行X操作否则执行Y操作”。这些分支逻辑是skill区别于普通prompt的关键它让Agent能根据输入动态调整行为。第三部分是工具声明列出这个skill需要用到哪些外部工具或MCP Server。比如一个网页抓取的skill可能需要声明它依赖Playwright MCP Server。这样在加载skill时系统可以自动检查依赖是否满足避免运行时才发现工具缺失。第四部分是示例给出几个典型的输入输出对。示例不需要多两三个就够但要覆盖主要场景和边界情况。示例的作用是让Agent更准确地理解指令的意图特别是在指令本身有歧义的时候示例能起到“锚定”的作用。第五部分是注意事项列出这个skill在使用中容易出错的地方。比如“不要对超过1GB的文件使用此skill会导致内存溢出”或者“如果API返回429状态码等待5秒后重试最多重试3次”。这部分往往是经验积累的结果新手写的skill通常缺少这一块导致Agent在遇到异常时不知道怎么处理。3.2 指令编写的颗粒度控制写skill指令时最难的把握颗粒度。写得太粗Agent自由发挥的空间太大结果不稳定写得太细Agent变成了只会按固定流程执行的机器人遇到新情况就卡住。我的经验是核心流程要细边缘情况要粗。比如一个“发送邮件”的skill核心流程应该写清楚验证收件人地址格式、检查附件大小、选择邮件模板、调用发送接口、记录发送日志。这些步骤每一步都不能少而且要明确顺序。但边缘情况可以写得灵活一些比如“如果发送失败根据错误码决定是重试还是通知用户”不需要把每种错误码对应的操作都列出来让Agent根据常识判断即可。另一个技巧是用“必须”和“建议”来区分优先级。必须做的事情用“必须”开头比如“必须在发送前验证收件人地址”。建议做的事情用“建议”开头比如“建议在邮件正文开头加上称呼”。这样Agent在资源有限或者时间紧迫时知道哪些可以妥协哪些不能。还有一个容易忽略的点是指令的否定形式。很多人写skill时只写“要做什么”不写“不要做什么”。但实际使用中Agent经常会做一些你不想让它做的事情。比如你写了一个“总结文档”的skillAgent可能会在总结里加入自己的评论这时候就需要明确写“不要添加原文中没有的观点”。否定指令往往比肯定指令更能约束Agent的行为。3.3 上下文窗口管理与Skill的加载策略Agent的上下文窗口是有限的而skill文件本身会占用一部分。如果一个skill写得太长比如超过5000字那加载它之后剩下的空间就不多了Agent处理实际任务时可能不够用。所以skill的篇幅需要控制。我的做法是把skill分成核心层和扩展层。核心层是必须加载的包含最基本的指令和工具声明通常控制在1000字以内。扩展层是可选加载的包含详细的示例、边缘情况处理、参考资料等只有在需要的时候才加载。这样Agent在大多数情况下只需要加载核心层节省上下文空间。另外多个skill同时加载时要注意它们之间的顺序。一般来说越具体的skill应该越靠后加载这样它的指令会覆盖前面更通用的skill。比如你有一个通用的“代码编写”skill和一个具体的“React组件编写”skill应该先加载通用的再加载具体的这样React相关的特殊要求会优先生效。还有一个技巧是用引用代替复制。如果两个skill都需要用到同一段工具说明不要在每个skill里都复制一遍而是把这段说明放在一个公共文件里skill里用引用链接指向它。这样既节省空间又方便统一更新。3.4 版本管理与团队协作中的Skill治理当团队里多个人都在写skill时版本管理就成了问题。我见过最混乱的情况是同一个skill在不同人的机器上有不同的版本导致Agent的行为不一致排查问题时非常头疼。解决这个问题的第一步是把skill纳入版本控制。不管是Git还是其他工具skill文件应该和代码一样被管理起来。每次修改都要有commit记录说明改了什么、为什么改。这样当Agent行为发生变化时可以快速定位到是哪次修改导致的。第二步是建立skill的评审机制。新skill或者对现有skill的重大修改应该经过至少一个人的review。Review的重点不是代码风格而是指令的清晰度、边界情况的覆盖、以及是否与其他skill冲突。我通常会让review的人模拟几个场景看看按照skill的指令走下来结果是否符合预期。第三步是定期清理废弃的skill。项目迭代过程中有些skill可能已经不再使用了但还留在仓库里。这些废弃的skill不仅占地方还可能被误加载。我习惯每个季度做一次skill盘点把过去三个月没有使用记录的skill标记为“待废弃”再过一个月还没有使用就删除。第四步是文档化skill的依赖关系。有些skill依赖于特定的MCP Server或者环境变量这些依赖应该在文档里写清楚。新成员加入时按照文档配置环境就能避免“为什么我的Agent跑不起来”这类问题。4. 实操过程从零安装并运行一个Skill4.1 环境准备与npx的配置要点在开始安装skill之前需要确保基础环境就绪。最核心的是Node.js和npm因为大多数skill的安装和运行都依赖npx。Node.js的版本建议用LTS版本比如18.x或20.x太新的版本可能有些包还没适配太旧的版本可能缺少某些API。安装Node.js的方式有很多我推荐用nvmNode Version Manager来管理这样可以在不同项目之间切换Node版本。在macOS或Linux上可以用curl安装nvm然后nvm install 20。在Windows上可以用nvm-windows安装过程稍微麻烦一点但用起来和macOS差不多。装好Node.js之后检查一下npm的registry配置。默认的registry在国内访问可能比较慢可以换成国内的镜像源。命令是npm config set registry https://registry.npmmirror.com。这个操作能显著提升npx下载包的速度减少超时失败的概率。还有一个容易忽略的配置是npx的缓存目录。默认情况下npx会把下载的包缓存在用户目录下的.npm/_npx文件夹里。如果这个文件夹所在的分区空间不足会导致安装失败。可以通过npm config set cache /path/to/larger/disk来修改缓存位置。我一般会把它设在一个空间充足的盘上避免因为磁盘满导致的各种奇怪报错。4.2 安装一个Skill的完整命令与参数说明假设我们要安装一个用于网页自动化的skill它依赖Playwright。典型的安装命令是npx playwright install。这个命令会下载Playwright的浏览器二进制文件包括Chromium、Firefox和WebKit。如果只需要Chromium可以用npx playwright install chromium来节省下载时间和磁盘空间。执行这个命令时npx会先检查本地是否有Playwright包如果没有就从registry下载。下载完成后它会根据当前操作系统下载对应的浏览器二进制文件。在Linux上可能还需要安装一些系统依赖比如libnss3、libatk-bridge2.0-0等。Playwright提供了一个命令npx playwright install-deps来自动安装这些依赖但在某些Linux发行版上可能需要sudo权限。安装完成后可以用npx playwright --version来验证是否成功。如果输出了版本号说明安装没问题。接下来就可以在skill文件里引用Playwright了。通常skill文件里会写类似“使用Playwright打开网页等待页面加载完成然后提取指定元素的内容”这样的指令。对于其他类型的skill安装方式可能略有不同。有些skill是纯指令文件不需要额外的二进制依赖直接下载Markdown文件放到指定目录即可。有些skill需要通过npm包的形式安装比如npx org/skill-name install。具体命令要看skill的文档但核心逻辑是一样的先确保运行时环境就绪再下载skill本身最后验证安装结果。4.3 配置Skill的加载路径与优先级安装完skill之后需要告诉Agent去哪里加载它。不同的Agent框架有不同的配置方式但通常都会有一个配置文件或者环境变量来指定skill的搜索路径。以常见的做法为例可以在项目根目录下创建一个.skills文件夹把下载的skill文件放进去。然后在Agent的配置文件里写上skills_path: ./.skills。这样Agent启动时会自动扫描这个文件夹加载里面所有的skill。如果同时有多个skill目录比如一个全局的skill目录和一个项目级的skill目录需要配置优先级。一般来说项目级的skill应该优先于全局的skill因为项目级的更具体。配置方式可能是skills_path: [./.skills, ~/.global-skills]Agent会按顺序加载后面的覆盖前面的同名skill。还有一个细节是skill的启用和禁用。有些skill可能只在特定任务中需要平时不想让它占用上下文。可以在配置文件里加一个enabled_skills列表只列出当前项目需要的skill。或者用disabled_skills列表来排除不想用的skill。我通常用白名单的方式只启用明确需要的skill避免意外加载了不相关的skill导致行为异常。4.4 验证Skill是否生效的三种方法装好skill之后怎么确认它真的生效了我常用三种方法。第一种是直接询问Agent。比如问它“你现在有哪些可用的skill”如果Agent能列出你刚装的skill名称和描述说明加载成功了。这个方法最简单但只能验证skill被识别了不能验证skill的逻辑是否正确执行。第二种是构造一个测试任务。比如你装了一个“JSON格式化”的skill就给它一个格式混乱的JSON字符串看它是否能按照skill里定义的规则输出格式化后的结果。这个方法能验证skill的核心逻辑但需要你设计好测试用例。第三种是查看日志。大多数Agent框架在加载skill时会输出日志显示加载了哪些文件、是否有解析错误、是否有依赖缺失。如果日志里有warning或error就需要进一步排查。我习惯在第一次安装skill后把日志级别调到debug仔细看一遍加载过程确认没有隐藏的问题。三种方法结合使用基本能覆盖大多数情况。如果三种方法都通过了但实际使用时还是有问题那可能是skill的指令本身有歧义需要回去修改skill文件。5. 常见问题与排查技巧实录5.1 npx playwright install失败的各种原因与对策npx playwright install失败是最高频的问题之一。根据我帮别人排查的经验原因可以分成几类。第一类是网络问题。表现是命令卡在“Downloading”阶段或者报错“ETIMEDOUT”。对策是换用国内镜像源或者设置代理环境变量。Playwright支持通过PLAYWRIGHT_DOWNLOAD_HOST环境变量来指定下载源。比如export PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright然后再执行安装命令。这个镜像源同步了Playwright的浏览器二进制文件下载速度会快很多。第二类是权限问题。在Linux上如果npm的全局目录需要sudo权限而你没有用sudo就会报“EACCES”错误。对策是修改npm的默认目录到用户有权限的位置命令是npm config set prefix ~/.npm-global然后把~/.npm-global/bin加到PATH里。这样以后安装全局包就不需要sudo了。第三类是磁盘空间不足。Playwright的三个浏览器加起来大概1GB左右如果磁盘剩余空间不够安装会中途失败。对策是清理磁盘或者只安装需要的浏览器比如npx playwright install chromium。另外可以把Playwright的缓存目录设到空间大的分区通过PLAYWRIGHT_BROWSERS_PATH环境变量来指定。第四类是系统依赖缺失。在Linux上Playwright的浏览器需要一些系统库比如libnss3、libatk1.0-0等。如果这些库没装浏览器启动时会报错。对策是运行npx playwright install-deps它会自动安装所需的系统依赖。如果这个命令也失败可以手动用包管理器安装比如在Ubuntu上sudo apt-get install libnss3 libatk1.0-0 libatk-bridge2.0-0。第五类是Node.js版本不兼容。有些Playwright版本要求Node.js 16以上如果你的Node.js太旧会报语法错误或者API不存在的错误。对策是升级Node.js到LTS版本。5.2 Skill加载后Agent行为不符合预期的排查思路有时候skill装好了日志也显示加载成功但Agent的行为就是不对。比如skill里写了“输出用JSON格式”但Agent还是输出Markdown。这种情况通常不是安装问题而是skill的指令没有被正确理解。排查的第一步是检查skill的优先级。如果同时加载了多个skill后面的skill可能会覆盖前面的。比如你有一个通用的“输出格式”skill说用Markdown又有一个具体的“API响应”skill说用JSON如果加载顺序不对可能通用的覆盖了具体的。解决方法是调整加载顺序把更具体的skill放在后面。第二步是检查指令的明确性。有些指令写得太模糊Agent可能理解成别的意思。比如“输出简洁”这种指令不同模型对“简洁”的理解不一样。可以改成“输出不超过三句话每句话不超过20个字”。越具体的指令执行结果越稳定。第三步是检查是否有冲突的指令。如果两个skill里都有关于输出格式的指令而且互相矛盾Agent可能会随机选一个执行。解决方法是合并这两个skill或者在一个skill里明确写“如果同时满足A和B条件优先执行A”。第四步是用示例来锚定行为。如果指令本身没问题但Agent还是跑偏可以在skill里加一两个示例明确展示期望的输入输出。示例对Agent的影响很大有时候比指令本身还管用。5.3 常见问题速查表问题现象可能原因排查方法解决方案npx命令卡住不动网络超时检查网络连接尝试ping registry换国内镜像源或设置下载主机环境变量报错EACCES权限不足检查npm全局目录权限修改npm prefix到用户目录或使用sudo浏览器启动失败系统依赖缺失查看错误日志中的缺失库名运行install-deps或手动安装系统库Agent不执行skill指令skill未加载或优先级低询问Agent可用的skill列表检查加载路径和顺序调整优先级Agent执行结果不稳定指令模糊或有冲突对比不同输入下的输出差异细化指令消除冲突增加示例skill加载报解析错误文件格式不正确查看日志中的具体错误行检查Markdown或JSON格式确保符合规范上下文窗口不足skill太长查看token使用量拆分skill为核心层和扩展层按需加载5.4 几个只有踩过坑才知道的细节第一个细节是skill文件的编码问题。如果skill文件里包含中文一定要确保文件是UTF-8编码。有些编辑器默认用GBK保存导致Agent读取时出现乱码指令就失效了。我习惯在文件开头加一个BOM标记或者在项目配置里强制指定编码。第二个细节是skill名称的大小写敏感。在Linux上文件名是大小写敏感的MySkill.md和myskill.md是两个不同的文件。如果配置里写的是小写但实际文件名是大写就会加载失败。建议统一用小写字母加连字符来命名skill文件避免这个问题。第三个细节是skill的依赖声明要完整。有些skill依赖特定的环境变量比如API密钥。如果skill文件里没有声明这个依赖Agent在运行时才发现缺少环境变量就会报错。好的做法是在skill的元信息里加上requires: [API_KEY]这样的声明加载时就能检查出来。第四个细节是skill的更新不会自动生效。如果你修改了skill文件但Agent还在用旧版本可能是因为Agent缓存了skill内容。大多数框架需要重启Agent或者执行一个reload命令才能加载新版本。我习惯在修改skill后先重启Agent再验证行为是否变化。第五个细节是多个skill之间的工具冲突。如果两个skill都声明需要Playwright但版本要求不同可能会导致其中一个无法正常工作。解决方法是统一工具版本或者在skill里明确指定兼容的版本范围。6. 进阶玩法自己写一个Skill并发布6.1 从需求到Skill的转化方法写skill的第一步不是打开编辑器而是想清楚这个skill要解决什么问题。我通常会用一句话描述需求比如“我需要一个skill能把会议记录整理成待办事项列表”。然后把这个需求拆解成几个步骤读取会议记录、识别其中的行动项、提取负责人和截止日期、格式化成待办列表、输出结果。拆解完之后针对每个步骤问自己几个问题这一步的输入是什么输出是什么有没有边界情况比如“识别行动项”这一步输入是一段文字输出是行动项列表。边界情况包括有些行动项没有明确的负责人有些没有截止日期有些是多人负责。这些边界情况需要在skill里写清楚怎么处理。然后考虑需要哪些工具。如果会议记录是文本文件可能只需要文件读取工具。如果是音频文件就需要语音转文字的工具。如果是网页上的会议记录就需要网页抓取工具。把这些工具列出来在skill的元信息里声明。最后是写指令。指令要按步骤写每一步都写清楚输入、操作、输出。对于边界情况用条件分支来处理。比如“如果行动项没有负责人标记为‘待分配’如果没有截止日期标记为‘待定’”。写完之后自己读一遍看看有没有歧义的地方。6.2 Skill文件的编写规范与模板一个可复用的skill模板大概长这样--- name: meeting-to-todo version: 1.0.0 description: 将会议记录整理成待办事项列表 requires: - file-reader - text-analyzer --- # 会议记录转待办事项 ## 指令 1. 读取当前工作目录下的meeting-notes.txt文件。 2. 分析文本识别所有以“行动项”、“待办”、“TODO”开头的段落。 3. 对每个行动项提取以下字段 - 任务描述行动项的主要内容 - 负责人如果文本中有“某人”或“由某人负责”提取该人名 - 截止日期如果文本中有日期格式提取该日期 4. 如果行动项缺少负责人标记为“待分配”。 5. 如果行动项缺少截止日期标记为“待定”。 6. 将所有行动项按截止日期排序日期近的在前。 7. 输出格式为Markdown表格包含任务描述、负责人、截止日期三列。 ## 示例 输入 行动项完成项目提案由张三负责截止日期2024-06-01。 待办联系供应商确认报价。 输出 | 任务描述 | 负责人 | 截止日期 | |---------|--------|---------| | 完成项目提案 | 张三 | 2024-06-01 | | 联系供应商确认报价 | 待分配 | 待定 | ## 注意事项 - 不要修改行动项的原始描述只做提取和格式化。 - 如果文本中没有找到任何行动项输出“未发现行动项”。 - 日期格式统一为YYYY-MM-DD。这个模板包含了元信息、指令、示例、注意事项四个部分。指令部分用有序列表每一步都很明确。示例部分给出了一个完整的输入输出对。注意事项部分列出了容易出错的地方。6.3 测试与迭代如何验证Skill的鲁棒性写完skill之后不能直接投入使用要先测试。我通常准备三组测试数据一组是正常情况一组是边界情况一组是异常情况。正常情况就是典型的输入比如上面例子中有一个完整的行动项。边界情况包括没有负责人的行动项、没有截止日期的行动项、日期格式不标准的行动项、多个行动项混在一起。异常情况包括文件不存在、文件为空、文件内容不是会议记录。对每组数据运行Agent并检查输出。如果输出符合预期就通过。如果不符合分析是skill指令的问题还是Agent理解的问题。如果是指令的问题修改指令如果是Agent理解的问题增加示例或者细化指令。测试通过后不要急着发布。先在自己的项目里用一周看看实际使用中还有没有没考虑到的情况。我经常在用了几天之后发现有些边界情况在测试时没想到但在实际使用中出现了。这时候就回去补充skill然后重新测试。6.4 发布与分享让更多人用上你的Skill如果你觉得自己的skill对别人也有用可以分享出去。分享的方式有几种。最简单的是把skill文件放到GitHub仓库里写一个README说明怎么安装和使用。如果skill比较通用可以发布到npm上让别人通过npx your-skill-name来安装。发布到npm的步骤是先在npm官网注册账号然后在项目目录下运行npm login登录再运行npm publish发布。发布之前要确保package.json里的name是唯一的version是新的。如果skill依赖其他包要在dependencies里声明。发布之后可以在技术社区里分享一下比如写一篇博客介绍这个skill解决了什么问题、怎么使用、有什么注意事项。也可以在其他人的skill基础上做改进然后提交pull request。开源社区的反馈往往能帮你发现没想到的问题也能让skill变得更完善。7. 我个人的一些使用体会用了几个月的Agent Skills最大的感受是它确实改变了我和AI协作的方式。以前我写prompt是“一次性”的每次都要重新描述需求。现在我把常用的流程写成skill需要的时候直接加载省去了大量重复描述的时间。而且skill是可以积累的今天写一个“代码审查”skill明天写一个“文档生成”skill慢慢地就形成了一套自己的工具库。另一个体会是skill的质量比数量重要得多。我见过有人收集了几十个skill但真正用的就那么几个。与其追求“skills大全”不如把常用的几个skill打磨好。一个好的skill应该是越用越顺手的每次遇到新情况就补充进去慢慢就变成了这个领域的“操作手册”。还有一个坑是不要过度依赖skill。有些任务其实用普通的prompt就能完成没必要非得写个skill。skill适合那些重复性高、流程固定、容易出错的任务。如果任务本身很灵活每次都不一样那写skill反而是一种负担。最后想说的是skills生态还在快速变化中。今天好用的工具明天可能就被替代了今天的最佳实践明天可能就过时了。保持学习的心态多试试新东西但也不要盲目追新。找到适合自己的工作流比什么都重要。