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、普通提示词、MCP（Model 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 这东西，跑通第一个之后，后面的路就顺了。
