1. 从“skills”这个热词说起它到底是什么为什么突然火了最近几个月不管是在技术社区、开发者群聊还是各种工具圈子里“skills”这个词出现的频率高得离谱。你随便翻翻热搜榜能看到skills、Google Cloud、Agent Skills、npx、GKE这些词绑在一起出现再往下刷claude agent skills: a first principles deep dive、codex skills、claude mcpservers npx、npx playwright install失败这类长尾词一个接一个。很多人第一次看到会懵这到底是个新框架某个云厂商的新产品还是又一个被炒起来的概念我先把结论摆在前面skills 不是某一个具体的软件而是一套让 AI Agent智能体具备“可插拔能力”的组织方式。你可以把它理解成给 AI 装“技能包”——每个 skill 就是一份结构化的说明文档告诉 Agent 在什么场景下该调用什么工具、按什么步骤执行、输出什么格式。它解决的核心问题是大模型本身只会“说”不会“做”而 skills 就是让它“会做”的那层胶水。为什么它现在火因为过去一年Agent 从 demo 走向生产大家发现光靠一个 system prompt 根本撑不住复杂任务。你需要让 Agent 会查数据库、会调 API、会跑测试、会生成报告还要能复用、能版本管理、能团队共享。skills 这套机制刚好补上了这块拼图。它适合谁前端开发者、后端工程师、做自动化测试的、搞数据管道的、甚至写论文做研究的人都能从中找到自己的用法。我见过有人用 skills 自动挖漏洞有人用它做分镜脚本有人用它把论文写作流程拆成十几个可复用步骤。今天我就把这套东西从头到尾拆一遍把踩过的坑和能直接抄的配置都给你。2. skills 的核心设计思路为什么是“文档驱动”而不是“代码驱动”2.1 一个 skill 的本质是什么很多人第一次接触 skills以为要写一堆代码。其实不是。一个 skill 的核心是一份 Markdown 文件通常叫SKILL.md放在一个独立目录里。这份文件用自然语言描述这个技能叫什么、什么时候触发、需要哪些输入、执行哪些步骤、输出什么结果、有哪些注意事项。Agent 在运行时读取这份文档结合当前上下文决定是否调用。为什么用文档而不是代码这是整个设计里最关键的取舍。代码驱动的方式比如写一个 Python 函数注册成 tool有几个硬伤第一非程序员改不动产品经理想把“生成周报”的步骤调整一下得找工程师改代码第二版本管理和 review 成本高一个 prompt 的微调可能牵扯到函数签名变更第三跨模型兼容性差不同模型对 tool schema 的理解不一样。而文档驱动把“能力描述”和“能力实现”解耦了——文档说清楚要做什么具体调用哪个工具、怎么调交给 Agent 自己判断。我实测下来这种方式的复用性远超预期。同一个code-reviewskill在 Claude 上用、在 Codex 上用、在本地跑的开源 Agent 上用只要模型能力够效果差异不大。这就是为什么热词里同时出现claude agent skills和codex skills——大家发现这套东西是跨平台的。2.2 目录结构长什么样一个标准的 skill 目录大概是这样my-skill/ ├── SKILL.md # 核心说明文档必须有 ├── scripts/ # 可选放辅助脚本 │ └── helper.py ├── templates/ # 可选放输出模板 │ └── report.md └── examples/ # 可选放示例输入输出 └── sample.mdSKILL.md里通常包含几个固定段落name技能名、description一句话描述Agent 靠这个判断是否触发、when_to_use使用场景、steps执行步骤、output_format输出格式、notes注意事项。这个结构不是强制的但社区里基本形成了共识因为 Agent 解析时对这几个字段的识别率最高。注意description这一行极其重要。它决定了 Agent 在什么情况下会想起你这个 skill。写得太窄永远不触发写得太宽到处乱触发。我建议用“动词对象场景”的格式比如“当用户要求审查代码质量并给出改进建议时使用”。2.3 和 MCP、npx 的关系热词里claude mcpservers npx和npx频繁出现这里得理清楚。MCPModel Context Protocol是另一套东西它解决的是“Agent 怎么连接外部工具和数据源”的问题偏底层通信。而 skills 解决的是“Agent 怎么组织和使用这些能力”的问题偏上层编排。两者是互补的MCP 提供工具skills 编排工具。npx则是 Node.js 生态里的包执行器很多 skill 的安装和分发走 npm 渠道所以你会看到npx skills install这类命令。npx playwright install失败这个热词说明很多人在装浏览器自动化相关的 skill 时卡住了这个我后面会专门讲怎么排查。3. 手把手搭建你的第一个 skill从零到能跑3.1 环境准备与前置检查在动手之前先确认你的环境。你需要一个能读取本地文件的 Agent 运行环境比如支持 skills 的 CLI 工具或者 IDE 插件。Node.js 版本建议 18 以上因为很多分发工具依赖较新的 npm 特性。检查命令node -v npm -v npx -v如果npx报错多半是 npm 没装好或者 PATH 没配。Windows 用户特别注意有时候全局安装的包不在 PATH 里需要手动加。我踩过的坑是在公司内网环境下npm registry 被指向了私有源导致npx拉不到公开包。解决办法是临时切回官方源npm config set registry https://registry.npmjs.org/装完之后再切回去。这个操作不影响你已有的私有包只是临时用一下。3.2 创建第一个 skill 目录假设我们要做一个“自动生成 Git 提交信息”的 skill。先建目录mkdir -p ~/.skills/git-commit-helper cd ~/.skills/git-commit-helper touch SKILL.md~/.skills/是社区约定的默认 skills 存放路径不同工具可能读不同位置但大多数会扫描这个目录。你也可以放在项目根目录的.skills/下这样能跟着项目走团队共享方便。3.3 编写 SKILL.md 的完整内容下面是我实际在用的一个版本你可以直接抄--- name: git-commit-helper description: 当用户需要根据代码变更生成规范的 Git 提交信息时使用 when_to_use: 用户执行 git diff 后要求生成 commit message或明确说帮我写提交信息 steps: 1. 运行 git diff --staged 获取暂存区变更 2. 分析变更涉及的文件类型和改动性质新增/修改/删除 3. 判断变更类型feat/fix/docs/style/refactor/test/chore 4. 生成符合 Conventional Commits 规范的提交信息 5. 如果变更跨多个类型拆分成多条建议 output_format: | 类型(范围): 简短描述 - 详细说明1 - 详细说明2 notes: | - 描述用中文类型关键词用英文 - 单行不超过 72 字符 - 不要编造未在 diff 中出现的改动 ---这里有几个细节值得说。---包裹的部分是 YAML front matterAgent 解析时优先读这里比正文更可靠。steps用有序列表Agent 会按顺序执行。output_format用代码块包裹避免格式被误解。notes里我特意写了“不要编造”因为早期版本 Agent 经常脑补一些没发生的改动加上这条之后明显收敛。3.4 测试与调试写完先别急着用手动测一遍。在终端里让 Agent 读取这个 skill然后在一个有改动的仓库里触发它。观察输出是否符合预期。如果没触发检查description是否够明确如果触发了但步骤乱检查steps是否太抽象。我常用的调试技巧是在SKILL.md里临时加一行debug: true然后看 Agent 的日志输出确认它读到了哪些字段。调完删掉这行。另一个技巧是把steps拆得更细宁可多写几步也不要让 Agent 自己猜。4. 进阶玩法把 skills 组合成工作流4.1 单一 skill 的局限一个 skill 只能干一件事。但真实任务往往是链条式的先分析需求再写代码再测试再生成文档。如果每个环节都手动触发效率提升有限。所以社区里开始流行“skill 编排”——用一个主 skill 去调用多个子 skill。热词里superpower skills和agent skills测试就是这类玩法的产物。superpower不是某个具体工具而是指把多个 skill 组合后产生的“超能力”效果。比如一个full-stack-featureskill内部依次调用requirement-analysis、code-gen、test-gen、doc-gen四个子 skill用户只需要说一句“帮我加个登录功能”剩下的自动跑完。4.2 编排的实现方式实现编排有两种路子。第一种是“显式调用”在主 skill 的steps里写明“调用 skill: code-gen”。这种方式可控性强但依赖 Agent 支持 skill 嵌套调用。第二种是“隐式触发”主 skill 只描述整体流程Agent 根据上下文自动匹配子 skill。这种方式灵活但不确定性高。我建议新手先用显式调用稳定之后再尝试隐式。下面是一个显式编排的示例--- name: full-stack-feature description: 当用户要求实现一个完整功能模块时使用 steps: 1. 调用 skill: requirement-analysis 拆解需求 2. 调用 skill: code-gen 生成代码 3. 调用 skill: test-gen 生成测试 4. 调用 skill: doc-gen 生成文档 5. 汇总所有产出输出最终报告 notes: | - 每个子 skill 的输出作为下一个的输入 - 如果任一环节失败暂停并报告 ---4.3 参数传递与状态管理编排里最麻烦的是参数传递。子 skill 怎么知道上一个 skill 产出了什么常见做法是用一个共享的上下文文件比如context.json每个 skill 读写这个文件。或者用 Agent 的会话记忆但这种方式在长流程里容易丢信息。我实测下来最稳的是“文件传递”每个 skill 把输出写到约定路径下一个 skill 从那里读。虽然土但可靠。比如requirement-analysis输出到./tmp/requirements.mdcode-gen读这个文件。路径写在SKILL.md的notes里Agent 会遵守。注意编排层数不要超过三层。超过三层之后调试难度指数上升而且 Agent 的上下文窗口可能不够用。我见过有人搞了七层嵌套最后自己都理不清哪一步出的错。5. 常见问题与排查技巧实录5.1 npx playwright install 失败怎么办这是热词里出现频率最高的问题之一。playwright是浏览器自动化库很多做网页测试、爬虫、截图的 skill 依赖它。npx playwright install失败通常有三个原因第一网络问题。Playwright 下载浏览器二进制文件时走的是 CDN国内网络经常超时。解决办法是设置镜像环境变量export PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright npx playwright install第二权限问题。Linux 下如果没写权限装到一半会报错。加sudo或者改安装路径export PLAYWRIGHT_BROWSERS_PATH$HOME/.cache/playwright npx playwright install第三版本不匹配。playwright包和浏览器版本要对应有时候 package.json 里锁的版本和实际装的不一致。删掉node_modules和package-lock.json重装通常能解决。5.2 skill 不触发或乱触发这是新手最常问的。不触发的原因九成在description写得太模糊。比如写“处理代码相关任务”Agent 根本不知道什么时候该用。改成“当用户要求重构函数并保持行为不变时使用”触发率立刻上来。乱触发则是description太宽泛。比如写“帮助用户”那什么任务它都想插一脚。解决办法是加限定词明确“不适用”的场景。我在notes里经常写“仅在用户明确要求 X 时使用不要主动触发”。5.3 输出格式不稳定Agent 有时候不按output_format来尤其是流程长的时候。我的经验是格式越简单越稳。能用纯文本就别用复杂嵌套能用固定标题就别用自由格式。另外在steps的最后一步明确写“按 output_format 输出不要添加额外解释”能显著提升一致性。下面这张表是我整理的常见问题速查问题现象可能原因排查动作解决方式skill 完全不触发description 模糊看 Agent 日志是否读取到 skill改写 description 为动词对象场景触发但步骤乱steps 太抽象检查 steps 是否可执行拆细步骤每步一个动作输出格式不对output_format 复杂对比实际输出与预期简化格式末尾加约束语句编排中断子 skill 失败定位失败环节加错误处理失败即暂停npx 安装失败网络/权限/版本看报错信息设镜像、改路径、清缓存重装5.4 国内安装 skills 的注意事项热词里claude 国内安装skills 官方市场说明很多人关心国内怎么装。核心就两点一是 npm 源二是二进制下载源。npm 源用npmmirror基本能解决大部分包下载问题。二进制源看具体工具Playwright 有镜像其他工具一般也有社区维护的镜像。如果实在拉不下来找同事要一份离线包手动放到缓存目录也能绕过。我个人的习惯是把常用的 skill 和依赖提前装好打包成一个本地目录新机器直接拷贝。这样不依赖网络也避免版本漂移。6. 真实场景拆解三个能直接抄的 skill 案例6.1 自动挖洞 skill 的拆解思路热词里自动挖洞skills听起来很唬人其实拆开看就是“安全扫描 结果分析 报告生成”三步。一个典型的vuln-scanskill 会这样写第一步调用静态分析工具扫代码第二步让 Agent 分析扫描结果判断误报第三步按 CVSS 格式生成报告。关键在第二步——纯工具扫描误报率极高Agent 的价值在于结合上下文过滤。我在notes里会写“只报告有明确利用路径的问题不确定的标记为待确认”。6.2 论文写作 skill 的流程设计codex写论文的skills这个热词背后是一整套学术写作流程。我见过一个做得不错的版本把论文拆成literature-review、method-design、experiment-analysis、writing、citation-check五个子 skill。每个子 skill 有独立的输出模板最后汇总。最有价值的是citation-check它会核对每条引用是否真实存在避免编造文献。这个功能在学术场景里太重要了。6.3 分镜脚本 skill 的实操分镜skills下载说明做视频的人也在用。一个分镜 skill 的输入是剧本或大纲输出是镜头列表包含镜号、景别、运镜、时长、画面描述、台词。核心难点是“景别和运镜的合理性”我在steps里加了一条“根据情绪强度选择景别紧张用特写舒缓用全景”效果比让 Agent 自由发挥好很多。7. 工具选型与生态现状7.1 主流运行环境对比现在支持 skills 的环境不少各有侧重。Claude 系对文档驱动支持最好解析SKILL.md最稳Codex 系在代码生成类 skill 上表现突出开源方案胜在可定制但需要自己搭。选哪个取决于你的主场景。如果主要写代码Codex 系优先如果做综合自动化Claude 系更均衡。7.2 skill 的分发与共享skills下载平台有哪些和skills大全这类需求说明大家想要一个集中的市场。目前还没有统一的官方市场主要靠 GitHub 仓库和社区列表。我建议自己维护一个skills仓库把团队常用的 skill 放进去用 git 管理版本。这样比依赖第三方市场可靠也方便内部 review。7.3 版本管理的最佳实践skill 也是代码需要版本管理。我的做法是每个 skill 目录下放一个CHANGELOG.md记录每次改动的原因和影响。重大改动升主版本号微调升次版本号。这样当 Agent 行为异常时能快速定位是不是最近改了某个 skill。8. 我踩过的坑和几条实在建议先说最大的坑不要一开始就追求大而全的 skill。我最早写了一个“全能助手”skill想把所有功能塞进去结果 Agent 每次触发都跑偏因为description太宽steps太长它根本执行不完。后来拆成十几个小 skill每个只干一件事反而稳定了。这个教训值不少时间。第二个坑是过度依赖 Agent 的自主判断。早期我在steps里写“根据情况选择合适的工具”结果它经常选错。后来改成“如果 X 则用工具 A如果 Y 则用工具 B”明确分支错误率大幅下降。Agent 不是人别指望它临场发挥把决策逻辑写死反而更好。第三个坑是忽略上下文长度。skill 编排层数多了之后每一步的输出都堆在上下文里很快就爆了。解决办法是每一步只保留关键信息中间产物写到文件里上下文里只放路径和摘要。最后分享一个实用技巧给每个 skill 加一个examples目录放两三个真实的输入输出样例。Agent 在读SKILL.md时会参考这些样例输出格式的准确率明显提升。这个技巧我是从写 prompt 的经验里迁移过来的实测有效。你要是刚开始搭自己的 skill 库从三五个高频场景入手跑通之后再扩展比一上来铺开要稳得多。