1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是泛泛而谈的能力清单或者某个招聘网站上的技能标签页。但结合热搜词里的 Agent Skills、Google Cloud、npx、AI agents、claude agent skills、codex skills 这些词来看这里说的 skills 并不是人类简历上的技能而是给 AI Agent 使用的一套可插拔能力包。你可以把它理解成给一个刚入职的智能体发的“员工手册加工具箱”手册告诉它遇到什么场景该做什么工具箱给它对应的脚本、模板、配置和参考资料。我最早接触这个概念是在折腾 Claude 的 Agent 能力扩展时。当时我手里有一个需要反复执行的流程读取一批结构化文档按固定规则抽取字段生成一份带目录的汇总文件再对结果做一轮格式校验。每次都要把同样的提示词重新粘贴一遍稍微改一点需求输出格式就跑偏。后来我把这套流程拆成一个 skill 目录里面放一个说明文件、几个脚本和一份模板Agent 每次只要加载这个 skill就能稳定复现整套动作。那一刻我的感受就是热搜里那句“今天学会了skills打开新世界”——它解决的不是“模型聪不聪明”的问题而是“模型能不能稳定、可复用、可协作地干一件具体的事”的问题。所以这篇内容我想聊的是Agent Skills 到底是什么、它的目录结构怎么设计、怎么从零开发一个能用的 skill、怎么安装和调试、以及在实际使用中会踩哪些坑。适合两类人看一类是已经在用 AI Agent 做自动化、但每次都要重复写提示词的开发者另一类是听说 skills 很火、想上手但被 npx、安装失败、市场下载这些词劝退的新手。我会尽量把每一步为什么这么做讲清楚而不是只丢一堆命令。需要先说明一点不同平台对 skills 的具体实现细节有差异下面讲的结构和流程是基于我实际使用中总结的通用做法具体到某个平台的字段名和加载路径你需要对照它的官方文档微调。但核心思路是相通的。2. Agent Skills 的核心设计思路拆解2.1 为什么需要 skills从“一次性提示词”到“可复用能力包”在没有 skills 之前我们让 Agent 干活的典型方式是写一段长提示词。提示词里塞进角色设定、任务步骤、输出格式、注意事项。这套做法在小任务上没问题但一旦任务变复杂问题就来了。第一是不可复用。你为“生成周报”写了一段提示词下周想生成月报虽然逻辑差不多但还是得重新改一遍。第二是不可维护。提示词越写越长改一个格式要求可能影响其他部分最后没人敢动。第三是不可协作。你把提示词发给同事他复制过去发现模型版本不一样、上下文不一样跑出来的结果完全不同。第四是无法携带资源。提示词只能描述“怎么做”但没法把要用的脚本、模板、示例数据一起打包。skills 的设计思路就是把这四件事一次性解决把一段能力封装成一个目录目录里有说明、有脚本、有资源、有示例Agent 按需加载用完即走。这跟传统软件工程里“把函数封装成模块”是一个道理。你不再每次重写逻辑而是调用一个已经测试过的模块。2.2 skills 和普通提示词、MCP 的区别在哪这里容易混淆的是 skills、普通提示词、MCPModel Context Protocol三者的关系。我用一个类比说明。普通提示词像是你临时给同事口头交代一件事说完就完了下次还得再说一遍。MCP 像是给同事开通了访问公司数据库和内部系统的权限解决的是“能拿到什么数据、能调用什么外部服务”的问题。而 skills 更像是给同事一本岗位操作手册里面写清楚了“遇到这类任务按这几步做用这几个模板注意这几个坑”。它解决的是“怎么把一件事做对、做稳、做一致”的问题。三者不冲突反而经常配合使用。一个典型的组合是MCP 负责连接外部数据源skill 负责定义处理这些数据的流程提示词负责触发这个 skill。热搜里出现的 claude mcpservers npx 这类词说的就是用 npx 去安装和启动 MCP 服务而 skills 则是另一条并行的能力扩展线。2.3 一个 skill 的最小构成目录结构与文件职责一个能用的 skill最小构成通常包含一个主说明文件和可选的资源目录。主说明文件一般用 Markdown 写里面包含几个关键部分这个 skill 是干什么的、什么时候该用它、使用步骤是什么、输入输出格式是什么、有哪些限制和注意事项。资源目录里可以放脚本、模板、参考文档、示例数据。我自己的习惯是这样一个目录结构my-skill/ ├── SKILL.md # 主说明文件Agent 首先读这个 ├── scripts/ # 可执行脚本比如数据处理、格式转换 ├── templates/ # 输出模板保证格式一致 ├── references/ # 参考资料比如字段定义、规则说明 └── examples/ # 输入输出示例帮 Agent 理解预期这个结构不是强制的但它的好处是职责清晰。Agent 读 SKILL.md 知道要干什么需要执行时去 scripts 找脚本需要套格式时去 templates 找模板遇到不确定的规则去 references 查拿不准输出长什么样就看 examples。这种“说明加资源”的组合正是 skills 比纯提示词强大的地方。注意SKILL.md 的写法直接决定 skill 能不能被正确触发。写得含糊Agent 就不知道该在什么时候用它写得啰嗦又会占用大量上下文。这个平衡后面会专门讲。3. 从零开发一个 skill 的完整实操3.1 先想清楚什么样的任务值得做成 skill不是所有任务都值得封装成 skill。我的判断标准有三条高频、有固定流程、对一致性要求高。三条都满足才值得投入时间做 skill。高频指的是这件事你会反复做比如每周生成报告、每次发版前检查清单、每批数据都要做的清洗。有固定流程指的是步骤基本不变不会每次都要临时决策。对一致性要求高指的是输出格式、字段、命名必须统一不能这次一个样下次一个样。反过来那种一次性的、探索性的、每次需求都不同的任务做成 skill 反而累赘。我见过有人把“帮我头脑风暴”也做成 skill结果就是每次触发都不太对因为头脑风暴本身就没有固定流程。3.2 写 SKILL.md把“什么时候用”和“怎么用”说清楚SKILL.md 是整个 skill 的灵魂。我写的时候会强制自己回答四个问题对应四个部分。第一部分是描述与触发条件。用一两句话说明这个 skill 做什么然后明确列出什么情况下应该使用它。这部分是给 Agent 做匹配用的关键词要准。比如一个“文档字段抽取”的 skill触发条件可以写成“当用户提供结构化文档并要求抽取指定字段、生成汇总表时使用”。第二部分是使用步骤。把流程拆成有序步骤每步说清楚做什么、用什么资源。步骤不要写得太细细到每行代码反而限制 Agent 的灵活性但关键决策点必须写清楚比如“如果字段缺失标记为待确认不要猜测”。第三部分是输入输出规范。输入是什么格式、必填哪些字段输出是什么格式、有哪些约束。这部分最好配 examples 里的示例让 Agent 有参照。第四部分是限制与注意事项。明确写出不该做什么比如“不要修改原始文档”“不要自行补充文档中没有的信息”。这些负面约束往往比正面步骤更重要因为它们防止 Agent 自作主张。3.3 配套脚本与模板让 skill 真正能干活光有说明文件skill 只能“指导”Agent不能“替”Agent 干活。真正提升稳定性的是配套脚本。比如格式转换、数据校验、文件生成这类确定性操作写成脚本比让模型每次现算要可靠得多。我一般用 Python 写脚本因为处理文本、表格、文件都很方便。脚本放在 scripts 目录下在 SKILL.md 里说明什么时候调用、传什么参数、期望什么输出。模板放在 templates 目录用占位符标记需要填充的位置。这样 Agent 的工作就变成了“读数据、调脚本、填模板”每一步都是确定的出错概率大幅降低。这里有个经验脚本的输入输出尽量用文件或标准格式不要依赖复杂的命令行参数。因为 Agent 调用脚本时参数传递容易出错。用“读一个 JSON 文件、写一个 JSON 文件”这种方式最稳。3.4 本地测试怎么验证一个 skill 真的能用写完 skill 别急着发布先在本地测。测试的核心是用不同的输入跑看输出是否稳定。我会准备三组测试数据一组标准输入验证正常流程一组边界输入比如字段缺失、格式不规范验证容错一组干扰输入比如文档里混入无关内容验证 Agent 会不会被带偏。测试时重点观察三件事Agent 有没有在正确的时机触发这个 skill、执行步骤有没有跳步或加戏、输出格式有没有跑偏。任何一项不稳定都要回去改 SKILL.md 或脚本。我自己的经验是一个 skill 平均要改三到五轮才能稳定第一版就能用的很少。4. 安装、分发与市场skills 怎么落地到实际环境4.1 安装方式盘点npx、手动放置与市场下载skills 的安装方式取决于你用的平台。常见的有三种。第一种是手动放置。把 skill 目录复制到平台约定的 skills 目录下重启或重新加载即可。这种方式最直接适合自己开发的 skill。第二种是通过命令行工具安装。热搜里出现的 npx 就是这类工具的代表。npx 本身是 Node.js 生态里的包执行工具很多平台用它来拉取和安装 skill 或 MCP 服务。典型命令形如npx some-skill-installer install skill-name。这种方式适合从远程仓库拉取别人做好的 skill。第三种是从市场下载。现在已经有平台提供 skills 市场可以浏览、搜索、一键安装。热搜里的“skills下载平台有哪些”“skills大全”“skills推荐”说的就是这类市场。市场的好处是有分类和评价坏处是质量参差不齐需要自己甄别。4.2 npx 安装失败的常见原因与排查npx 安装失败是热搜里的高频问题我自己也踩过。常见原因有这么几类。第一类是网络问题。npx 需要从远程仓库拉包网络不通就会卡住或超时。表现是命令执行很久没反应最后报超时错误。排查方法是先确认基础网络能通再试。第二类是Node.js 版本不匹配。有些 skill 要求特定版本的 Node.js版本太低会报语法错误或依赖缺失。用node -v看当前版本对照 skill 的要求。第三类是权限问题。在部分系统上全局安装需要管理员权限否则会报写入失败。这种情况可以改用本地安装或者调整目录权限。第四类是依赖冲突。如果本地已经装了同名但不同版本的包可能冲突。清理缓存后重试往往能解决。第五类是包本身的问题。有些 skill 发布时就没配好缺文件或配置错误。这种情况换一个来源或者直接手动下载目录放置。提示遇到 npx 安装失败先看报错信息的最后几行那里通常有真正的原因。不要被前面一大堆下载日志吓到。4.3 安装后的验证确认 skill 被正确加载装完不代表能用。我每次装完都会做三步验证。第一步确认 skill 目录出现在平台的 skills 列表里或者用平台的查看命令能看到它。第二步用一个最简单的输入触发它看是否被正确识别。第三步跑一个完整流程看输出是否符合预期。如果 skill 没被加载常见原因是目录层级不对、主说明文件命名不对、或者平台需要重启才生效。这些细节每个平台不一样装之前最好看一眼它的 skills 目录约定。5. 实战场景skills 在不同任务里的用法5.1 文档处理类 skill字段抽取与汇总这是我用得最多的一类。场景是手里有一批格式类似的文档需要按固定规则抽取字段汇总成一张表。没有 skill 的时候我每次都要写一大段提示词还要反复纠正格式。做成 skill 之后流程变成Agent 读文档、调抽取脚本、按模板生成汇总表、跑校验脚本。这类 skill 的关键在于字段定义要写死在 references 里不要让 Agent 自由发挥。哪些字段、什么类型、缺失怎么处理全部明确。脚本负责确定性抽取Agent 负责处理脚本搞不定的模糊情况。两者配合稳定性比纯提示词高一个量级。5.2 代码与工程类 skill检查清单与规范落地第二类常用的是工程检查类。比如发版前的检查清单、代码规范检查、依赖更新提醒。这类 skill 的价值在于把团队约定固化下来不依赖某个人记不记得。我做过一个发版检查 skill里面列了十几项检查版本号是否更新、变更日志是否填写、测试是否通过、依赖是否有已知问题。Agent 按清单逐项检查输出一份检查报告。以前这些靠人肉记总会漏现在跑一遍 skill几分钟出结果。5.3 内容创作类 skill分镜与结构化输出热搜里出现了“分镜skills下载”说明内容创作领域也在用。分镜这类任务的特点是结构固定但内容多变。一个分镜 skill 可以定义好分镜的字段镜号、画面描述、台词、时长、备注。Agent 负责根据脚本内容填充这些字段模板负责保证输出格式统一。这类 skill 的难点在于创意和结构的平衡。结构太死输出千篇一律结构太松又失去 skill 的意义。我的做法是结构固定、内容开放字段必须填但怎么填交给 Agent。6. 常见问题与避坑经验实录6.1 skill 不被触发怎么办最常见的问题是 skill 写好了但 Agent 不用。原因通常是 SKILL.md 里的触发条件写得太窄或太模糊。太窄匹配不上太模糊Agent 不确定该不该用。解决办法是把触发条件写成“当用户做 X 且需要 Y 时使用”既有场景又有意图。另一个原因是 skill 太多互相干扰。这时候要精简把不常用的 skill 移出加载目录或者给每个 skill 更明确的边界。6.2 输出格式不稳定的排查思路输出格式跑偏八成是模板不够明确或者 Agent 没读到模板。检查两件事SKILL.md 里有没有明确说“必须使用 templates 里的模板”模板里的占位符有没有写清楚。如果还不行就在 examples 里放一个完整的输入输出示例让 Agent 照着抄。6.3 skill 之间的冲突与优先级当多个 skill 都能处理同一个请求时会冲突。解决办法是给 skill 分优先级或者在 SKILL.md 里写明“本 skill 优先于某某场景”。更彻底的做法是合并相关 skill减少重叠。6.4 版本管理与更新策略skill 也是代码需要版本管理。我习惯在 SKILL.md 顶部写版本号和更新日期每次改动都记一笔。更新时先在小范围测试确认没问题再替换正式版本。不要直接改线上在用的 skill出问题会影响所有依赖它的流程。常见问题可能原因排查方向skill 不被触发触发条件模糊或过窄改写触发条件明确场景和意图输出格式跑偏模板不明确或未加载检查模板引用和示例安装失败网络、版本、权限、依赖看报错最后几行逐项排查skill 冲突多个 skill 职责重叠分优先级或合并更新后出问题未测试直接替换先小范围测试再上线7. 我对 skills 这套机制的个人体会用了一段时间 skills 之后我最大的感受是它把 AI 使用从“手艺”变成了“工程”。以前用 AI 干活靠的是提示词写得好不好有点像手艺人凭经验现在用 skills靠的是能力封装得好不好更像工程师在搭模块。这个转变对个人来说意味着可积累对团队来说意味着可协作。我踩过的最大的坑是一开始想把所有东西都做成 skill。结果做了一堆互相干扰维护成本还高。后来我收敛到只做高频、固定、要求一致的任务反而效果好。另一个坑是SKILL.md 写太细细到每句话都规定死Agent 反而不会灵活处理边界情况。现在的做法是流程写清楚、边界写清楚、中间留空间。如果让我给刚上手的人一条建议那就是先从一个你每周都要做、步骤固定的小任务开始做一个最小可用的 skill跑通再说。不要一上来就追求大而全也不要被安装失败吓退。skills 这东西跑通第一个之后后面的路就顺了。