1. 从skills这个热词说起它到底在解决什么问题最近一段时间skills这个词在开发者圈子里出现的频率明显高了起来。如果你在技术社区里刷到过claude agent skills、codex skills、agent skills 测试这类词大概率会有点懵——这到底是个新框架、新工具还是某种插件机制我一开始也是同样的反应直到自己动手把一整套 skills 从零搭起来、跑通、踩了几个坑之后才算真正理解它想干的事情。先把结论摆在前面skills 本质上是一种把可复用的能力封装成独立模块再按需加载给 AI Agent 使用的组织方式。你可以把它理解成给 AI 助手准备的技能包——每个 skill 就是一份说明书加一套工具告诉 Agent 在遇到某类任务时该怎么做、能用哪些命令、遵循什么流程。它不是一个具体的软件而更像是一种约定俗成的目录结构和描述规范。为什么这个东西会突然火起来因为大家在实际用 AI 写代码、做自动化任务的时候普遍遇到同一个痛点通用模型什么都懂一点但什么都不精。你让它写个 Playwright 脚本它能写但经常漏掉等待逻辑你让它处理 GKE 上的部署它知道概念但具体到kubectl的参数就含糊了。每次都要重新贴一遍上下文、重新纠正效率极低。skills 的出现就是把这些领域内的正确做法固化下来让 Agent 每次都能按同一套标准执行。这篇文章适合谁看如果你是刚听说 skills、想搞清楚它到底是什么的前端或全栈开发者或者是已经在用 Claude、Codex 这类工具、想让它们更听话的进阶用户再或者你是团队里负责搭建 AI 工作流的技术负责人那这篇内容应该能帮你少走不少弯路。我会从概念拆解讲到目录结构从安装踩坑讲到实际开发一个自己的 skill尽量把每个为什么都讲透。需要提前说明的是skills 目前还处在快速演进的阶段不同平台Claude、Codex、各类 Agent 框架的实现细节有差异但核心思路是相通的。我下面讲的内容以通用实践为主具体到某个平台时会单独标注。2. 拆开一个 skill 看内部目录结构与核心文件2.1 为什么是文件夹 Markdown这种朴素形态第一次看到 skill 的目录结构时我其实有点意外——它没有想象中那么工程化。一个典型的 skill 长这样my-skill/ ├── SKILL.md ├── scripts/ │ └── helper.py ├── references/ │ └── api-notes.md └── assets/ └── template.json核心就是那个SKILL.md剩下的都是可选资源。这种设计看起来简单但背后有很实际的考量。AI Agent 在加载 skill 时第一步读的就是SKILL.md里的元信息名称、描述、触发条件只有判断这个 skill 和当前任务相关时才会进一步读取正文和引用文件。这种渐进式加载机制非常关键——如果每个 skill 都把全部内容塞进上下文几十个 skill 叠加起来直接把 token 预算吃光。所以SKILL.md的写法直接决定了这个 skill 好不好用。它通常包含两部分头部是 YAML 格式的元数据frontmatter下面是 Markdown 正文。元数据里最重要的两个字段是name和description前者是唯一标识后者是给 Agent 看的广告词——写得越具体Agent 判断是否调用就越准。提示description千万别写成帮助处理各种任务这种废话。要写成当用户需要解析 PDF 表格并导出为 CSV 时使用此技能把触发场景写清楚命中率会高很多。2.2 SKILL.md 正文该写什么流程、约束、示例三件套正文部分我摸索出一个比较稳的结构基本是流程 约束 示例三件套。流程是告诉 Agent 做这件事的标准步骤。比如一个生成周报的 skill流程可能是先读取本周的 git log再按模块归类 commit然后套用固定模板输出。步骤要写成有序列表每步都明确输入和输出。约束是那些容易做错但很重要的规则。这部分是 skill 真正的价值所在。举个例子在写 Playwright 相关的 skill 时我会明确写上禁止使用page.waitForTimeout()做固定等待必须用waitForSelector或expect().toBeVisible()。这种约束如果只靠模型自己发挥十次里有三次会偷懒用固定等待。示例则是给 Agent 的参考答案。一段好的输入输出示例比三段文字描述都管用。我一般会放一个典型输入 → 期望输出的对照再放一个边界情况的处理示例。2.3 scripts 和 references什么时候该拆出去很多人一开始会把所有东西都塞进SKILL.md结果文件越写越长加载慢、维护也乱。我的经验是能确定性执行的逻辑放 scripts需要查阅的知识放 references。scripts/里放的是可以直接运行的脚本比如一个数据清洗的 Python 文件、一个调用 API 的 shell 脚本。Agent 遇到这类任务时直接执行脚本比让它现场生成代码更可靠——毕竟脚本是你调试过的而模型生成的代码每次都可能不一样。references/里放的是参考资料比如某个 API 的字段说明、某个规范的详细条款。这些内容不需要 Agent 全部记住只在需要时查阅即可。这种拆分让 skill 的常驻成本很低但能力上限很高。目录放什么加载时机典型内容SKILL.md元信息 核心流程判断相关后加载步骤、约束、示例scripts/可执行脚本需要执行时调用Python、Shell、Node 脚本references/参考文档需要查阅时读取API 文档、规范说明assets/静态资源按需引用模板、配置、样例数据3. 安装与加载npx 那条命令背后的门道3.1 为什么大家都用 npx 来装 skills热词里频繁出现npx这不是偶然。skills 的分发目前主流方式是通过 npm 包或者 Git 仓库而npx的好处是用完即走、不污染全局环境。一条典型的安装命令大概长这样npx skills-cli install skill-name或者直接从仓库拉npx skills-cli add github:user/reponpx会临时下载 CLI 工具、执行安装、把 skill 放到约定的目录里通常是项目下的.skills/或用户级的配置目录。这种方式的优点是版本可控、跨平台一致缺点是首次执行会慢因为要下载依赖。我实测下来如果网络环境一般第一次跑npx命令可能要等十几秒甚至更久。这时候别急着以为卡死了先看看是不是在下载。如果反复失败可以先把 CLI 全局装一次后续调用会快很多npm install -g skills-cli skills-cli install skill-name3.2 npx playwright install 失败一个高频坑的完整排查说到npx就不得不提那个被搜爆的问题——npx playwright install 失败。这个坑我踩过不止一次而且它和 skills 场景高度相关因为很多做前端自动化、页面测试的 skill 都依赖 Playwright。失败的表现通常是卡在下载浏览器二进制文件那一步报错五花八门有的是超时有的是权限拒绝有的是磁盘空间不足。我总结了一套排查顺序按这个走基本能定位第一步确认是不是网络问题。Playwright 安装时会去下载 Chromium、Firefox、WebKit 三个浏览器体积不小。如果卡在Downloading阶段不动八成是网络。可以设置镜像源或者只装需要的浏览器# 只装 Chromium省时间省空间 npx playwright install chromium第二步检查缓存目录权限。在 Linux 或 macOS 上Playwright 默认把浏览器放在~/.cache/ms-playwright。如果这个目录之前被 root 创建过普通用户就没权限写入。解决办法是改属主或者清掉重来sudo chown -R $USER ~/.cache/ms-playwright第三步看系统依赖是否齐全。在 Linux 上浏览器运行需要一堆系统库比如libnss3、libatk之类。缺库的话安装能过但运行会崩。可以用官方命令补依赖npx playwright install-deps第四步确认 Node 版本。新版 Playwright 对 Node 版本有要求太老的 Node 会直接报错。用node -v看一眼低于要求就升级。注意如果你是在 CI 环境里跑记得把浏览器缓存目录做成持久化缓存否则每次构建都要重新下载慢到怀疑人生。3.3 skill 加载不生效先查这三个地方装完 skill 却发现 Agent 根本不用它这种情况太常见了。我一般按这个顺序查目录位置对不对不同平台约定的 skill 目录不一样有的读项目根目录的.skills/有的读用户配置目录。装错地方等于没装。SKILL.md 的 frontmatter 格式对不对YAML 对缩进极其敏感多一个空格都可能解析失败。建议用工具校验一下。description 是否命中当前任务如果描述写得太泛或太窄Agent 判断不相关就不会加载。这时候可以临时在对话里明确点名这个 skill看它能不能被唤起。4. 自己动手写一个 skill从需求到跑通4.1 选一个高频且易错的场景切入写 skill 最忌讳一上来就搞个大而全的。我的建议是挑一个你每周都要做、而且每次都要重新解释的场景。这种场景写出来的 skill 收益最明显。举个我自己的例子。我经常需要把一堆散乱的 Markdown 笔记整理成结构化文档每次都要跟 AI 强调保留原文、按主题归类、生成目录、别改我的措辞。说了无数遍还是偶尔跑偏。于是我决定把这个流程固化成一个 skill。4.2 把口头指令翻译成结构化描述写SKILL.md的过程其实就是把你脑子里那些默认规则显式写出来。我一开始写得很随意结果 Agent 执行时还是老样子。后来我强迫自己按输入 → 处理 → 输出 → 禁忌四段式来写效果立刻不一样。--- name: note-organizer description: 当用户提供散乱的 Markdown 笔记并希望整理成结构化文档时使用。适用于笔记归类、目录生成、格式统一等场景。 --- ## 处理流程 1. 通读全部输入识别主题边界 2. 按主题聚类每个主题生成二级标题 3. 保留原文措辞仅调整顺序和层级 4. 在开头生成目录 ## 硬性约束 - 禁止改写用户原文的任何句子 - 禁止删除任何一条笔记 - 主题名称必须来自原文关键词不得自创 ## 示例 输入三段关于部署和调试的零散笔记 输出一级标题部署下含两段调试下含一段开头带目录这里的关键是约束要写成禁止而不是尽量。模型对禁止这类强指令的遵循度明显更高。4.3 用测试用例验证 skill 是否真的稳定skill 写完不算完得测。我一般会准备三组用例典型用例正常输入、边界用例空输入、超长输入、干扰用例输入里混入无关内容。跑一遍看输出是否符合预期。如果发现某类用例总是失败说明约束写得不够明确回去补。这个过程可能要迭代两三轮但一旦稳定下来后面就是纯收益了。测试类型输入特点关注点常见问题典型用例标准格式、内容完整流程是否走通步骤遗漏边界用例空、超长、格式异常是否崩溃或乱来无兜底逻辑干扰用例混入无关内容是否被带偏约束不够强5. 进阶玩法让多个 skill 协同工作5.1 skill 之间的调用与依赖怎么处理当你有了几个 skill 之后自然会想让它们配合。比如一个抓取网页数据的 skill 和一个生成报表的 skill能不能串起来用答案是能但要注意职责边界。我的原则是每个 skill 只干一件事跨 skill 的编排交给 Agent 或者外层的工作流。如果让 skill A 直接去调用 skill B耦合度就上去了改一个坏一片。实际操作中我会在SKILL.md里写清楚本 skill 的输出格式这样下游 skill 就能稳定接收。比如抓取 skill 固定输出 JSON报表 skill 固定读 JSON中间用格式约定来解耦。5.2 版本管理与团队共享的实践skill 一旦在团队里用起来版本管理就成了问题。我的做法是把 skill 当代码管放进 Git 仓库用语义化版本号改动写 changelog。共享方面小团队直接共享仓库就行大团队可能需要一个内部的 skill 市场让大家能搜索、安装、评分。热词里出现的skills 下载平台skills 大全其实反映的就是这种需求——大家想要一个集中的地方找现成的 skill。不过我得提醒一句别盲目装一堆 skill。每个 skill 都会占用 Agent 的判断成本装太多反而会让它选择困难。我一般控制在十个以内定期清理不用的。5.3 安全边界skill 能执行代码意味着什么这是最容易被忽视的一点。skill 里的scripts/是可以被执行的如果来源不可信风险很大。我给自己定了三条规矩只装自己能看懂源码的 skill尤其是带脚本的脚本里禁止出现删除、覆盖类的高危操作除非有明确确认敏感操作比如访问外部服务单独隔离不和其他 skill 混在一起提示团队内部共享 skill 时最好加一道 review 流程别让谁随手提交的脚本直接进生产环境。6. 那些搜索框里没人告诉你的实操心得6.1 description 的写法决定了 80% 的命中率我前面提过一次这里再强调因为它真的太重要了。我做过对比测试同一个 skilldescription 写得模糊时Agent 十次任务里只调用两三次改成精确描述后命中率能到八九成。写 description 的诀窍是用当……时使用的句式把触发场景写具体。比如当用户需要把 Excel 转成图表时使用就比数据处理技能强太多。另外可以适当堆一些同义词覆盖不同的表达习惯。6.2 别把 skill 写成万能工具箱新手最容易犯的错就是想把所有相关功能塞进一个 skill。结果就是SKILL.md又臭又长Agent 加载慢、判断也不准。一个 skill 解决一类问题宁可拆细一点。拆细之后每个 skill 的 description 都能写得很精准整体命中率反而更高。6.3 定期体检你的 skill 库skill 不是写完就一劳永逸的。模型在更新、你的工作流在变半年前好用的 skill 现在可能已经过时。我每个月会花半小时过一遍自己的 skill 库看看哪些还在用、哪些可以合并、哪些该删。这个习惯帮我省了不少上下文预算。6.4 从抄开始但一定要改热词里skills 推荐skills 大全说明大家都想找现成的。我的建议是可以拿来当起点但一定要按自己的场景改。别人的 skill 是别人的工作流直接套用往往水土不服。我一般会先跑一遍别人的 skill看它的流程和约束然后照着思路重写一版贴合自己的。7. 关于 skills 这件事我目前的判断用了一段时间下来我对 skills 的定位越来越清晰它不是什么颠覆性的新技术而是把提示词工程从一次性对话升级成了可维护的工程资产。以前你调好一段提示词用完就散了现在你可以把它固化成一个 skill反复用、持续改、团队共享。它真正的价值不在于让 AI 变聪明而在于让 AI 变稳定。通用模型的能力已经够强了缺的是每次都按同一套标准执行的可靠性。skills 补的正是这块。如果你还没开始用我的建议是从一个你每周都做、每次都烦的小任务开始写第一个 skill。别追求完美先跑通再迭代。等你有了三五个稳定的 skill回头看会发现和 AI 协作的体验完全不一样了。至于那些还在纠结skills 官方下载国内怎么装的问题其实核心就一句话搞清楚你的平台读哪个目录把文件放对位置剩下的都是细节。真正花时间的永远是内容本身——也就是你怎么把一件事讲清楚让 Agent 一次就做对。