1. 从“skills”这个标题说起它到底在指什么第一次看到“skills”这个标题很多人会以为是某个招聘网站上的技能标签或者是一份简历里的能力清单。但结合热搜词里反复出现的 Agent Skills、Google Cloud、npx、AI agents、claude agent skills、codex skills 这些词基本可以确定这里说的 skills 不是人类职场意义上的技能而是给 AI Agent 使用的一种可插拔能力模块。说得再直白一点大模型本身是一个“什么都懂一点但什么都做不精”的通才。你让它写一段代码它能写你让它查一个数据库它得靠你喂上下文你让它操作浏览器点一个按钮它默认做不到。skills 就是把这些“做不到”或者“做不好”的事情封装成一个个独立的、可被 Agent 调用的能力包。每个 skill 通常包含一段说明告诉 Agent 这个技能是干什么的、什么时候用、一份执行逻辑可能是脚本、可能是 API 调用、可能是提示词模板以及必要的依赖声明。这个思路其实不新鲜早几年做 RPA 的时候就有类似的概念叫“动作库”或者“组件库”。但 skills 和传统 RPA 组件的区别在于RPA 组件是给人拖拽用的skills 是给 AI Agent 自主决策调用的。Agent 会根据当前任务上下文自己判断“我现在需要调用哪个 skill”而不是等人来指定。这就把自动化的门槛从“会配流程”降到了“会描述需求”。热搜词里还有几个值得注意的信号npx playwright install失败、claude mcpservers npx、claude 国内安装skills 官方市场、skills下载平台有哪些、skills安装包下载。这些词说明两件事第一skills 的分发和安装已经形成了类似 npm 包管理的生态第二大量用户在安装环节卡住了尤其是涉及 npx 和浏览器依赖的时候。这正好是本文要重点拆解的部分。这篇文章适合三类人看一是刚接触 AI Agent、想搞清楚 skills 到底是什么的开发者二是已经在用 Claude、Codex 这类工具但不知道怎么扩展其能力边界的人三是想自己写 skill 并分发给别人用的进阶玩家。我会从设计思路讲到实操步骤再到踩坑记录尽量把每个环节的“为什么”说清楚。2. skills 的整体设计思路与生态拆解2.1 为什么是“技能包”而不是“插件”很多人第一次听到 skills会下意识把它类比成浏览器插件或者 VSCode 扩展。这个类比方向对但细节差很远。浏览器插件是寄生在宿主程序里的它依赖宿主提供的 API 和生命周期而 skill 是独立于 Agent 存在的Agent 只是“调用方”skill 本身可以是一个命令行工具、一个 HTTP 服务、甚至一段纯文本提示词。这个设计选择背后的逻辑是解耦。如果 skill 必须依赖某个特定 Agent 的运行时那它就锁死了。今天你用 Claude明天想换 Codexskill 就得重写。而把 skill 做成独立的能力单元之后只要 Agent 支持“读取 skill 描述并调用”这个通用协议skill 就可以跨平台复用。热搜词里同时出现了claude agent skills和codex skills说明这两个平台都在推自己的 skills 体系但底层的 skill 格式有趋同的趋势。目前主流的做法是用一个 Markdown 文件描述 skill 的元信息名称、描述、触发条件、参数再用一个可执行文件或者脚本目录承载实际逻辑。Agent 启动时扫描 skills 目录把每个 skill 的描述读进上下文需要的时候再调用。注意skill 的描述文件写得越清楚Agent 判断“什么时候该用这个 skill”的准确率就越高。很多人写 skill 只写功能不写触发场景结果 Agent 要么不用要么乱用。2.2 skills 生态里的三个角色把热搜词里出现的概念归归类整个 skills 生态可以分成三个角色角色代表关键词职责skill 开发者skills开发、github skills编写 skill 逻辑、定义元信息、发布到仓库skill 分发平台skills下载平台、官方市场托管 skill 包、提供搜索和版本管理skill 运行宿主Claude、Codex、AI agents扫描本地 skills、按需调用、回传结果这三个角色里分发平台是最不稳定的。热搜词里有人问“skills下载平台有哪些”说明目前还没有形成一家独大的局面。GitHub 是最常见的分发渠道很多 skill 直接以仓库形式存在用户 clone 下来放到指定目录就能用。官方市场则在做审核和版本管理但覆盖范围有限。对普通用户来说最实际的路径是先从 GitHub 上找现成的 skill手动放到本地 skills 目录跑通了再考虑要不要自己写。一上来就自己写 skill很容易在依赖配置和路径问题上卡住挫败感很强。2.3 一个 skill 的最小结构不管哪个平台一个能跑的 skill 至少包含这几样东西元信息文件通常叫SKILL.md或者skill.json里面写清楚 skill 名称、一句话描述、详细说明、参数列表、使用示例。执行入口可以是一个 shell 脚本、一个 Python 文件、一个 Node.js 脚本或者一个指向外部服务的 URL。依赖声明如果 skill 依赖某个 npm 包或者 Python 库需要在这里写清楚方便安装时自动拉取。我见过最简单的 skill 就是一个 Markdown 文件加一个 bash 脚本总共不到 50 行但能完成“查询某个 API 并格式化返回”这件事。也见过复杂的 skill 包含整个 Playwright 浏览器自动化流程依赖几十个包。skill 的复杂度完全取决于你要它干什么没有固定模板。实操心得刚开始写 skill 的时候尽量把逻辑写在一个文件里不要一上来就搞模块化。等这个 skill 稳定运行了一两周再考虑拆分成多个文件。过早抽象是新手最容易犯的错误。3. 核心细节解析skill 的元信息与触发机制3.1 元信息文件里到底该写什么元信息文件是 Agent 决定“要不要用这个 skill”的唯一依据。Agent 在启动时会把所有 skill 的元信息读进上下文但不会读执行逻辑。所以元信息写得好不好直接决定了 skill 的命中率。一份合格的元信息至少包含以下字段nameskill 的唯一标识用英文小写加连字符比如web-page-screenshot。description一句话说清楚这个 skill 能做什么控制在 50 字以内。when_to_use什么场景下应该调用这个 skill。这是最关键的字段要写得具体比如“当用户要求对某个网页进行截图并保存为图片时使用”。parameters参数列表每个参数写明名称、类型、是否必填、示例值。examples至少给一个调用示例让 Agent 知道怎么传参。很多人写 description 的时候喜欢写“这是一个用于处理网页截图的技能”这种写法对 Agent 来说信息量太低。更好的写法是“对指定 URL 的网页进行全页截图返回图片文件路径”。描述里要包含动作、对象、返回结果三个要素。3.2 Agent 是怎么决定调用哪个 skill 的Agent 的决策过程大致分三步意图识别解析用户输入判断当前任务需要什么能力。技能匹配把所有 skill 的 description 和 when_to_use 拿出来跟当前意图做语义匹配。参数填充从用户输入和上下文里提取参数填入匹配到的 skill。这个过程中最容易出问题的是第二步。如果两个 skill 的描述有重叠Agent 可能会选错。比如你有一个web-screenshot和一个web-snapshot描述都写“对网页进行截图”Agent 就懵了。解决办法是在 when_to_use 里写清楚区别前者用于“需要图片文件”后者用于“需要 HTML 快照”。注意skill 数量超过 20 个之后Agent 的匹配准确率会明显下降。这时候需要做分组或者用更结构化的方式组织元信息。我自己的做法是按领域分目录每个目录下的 skill 数量控制在 10 个以内。3.3 参数传递的三种方式skill 接收参数的方式主要有三种各有适用场景命令行参数适合简单的字符串和数字比如--url https://example.com。优点是直观缺点是复杂结构不好传。环境变量适合敏感信息比如 API key。优点是安全缺点是调试麻烦。标准输入stdin适合大段文本或者 JSON 结构。优点是灵活缺点是需要 skill 自己解析。我一般建议简单参数走命令行敏感信息走环境变量复杂结构走 stdin。如果一个 skill 需要传超过 5 个参数就应该考虑把参数合并成一个 JSON 通过 stdin 传入而不是堆一长串命令行参数。# 命令行参数示例 ./skills/web-screenshot/run.sh --url https://example.com --output /tmp/shot.png # stdin 传 JSON 示例 echo {url: https://example.com, output: /tmp/shot.png} | ./skills/web-screenshot/run.sh两种方式都能跑但第二种在参数多的时候更清晰也更容易被 Agent 自动生成。4. 实操过程从零安装并跑通第一个 skill4.1 环境准备与依赖检查在装任何 skill 之前先把基础环境确认一遍。热搜词里npx playwright install失败出现频率很高说明很多人的问题出在依赖环节。需要确认的东西Node.js 版本建议 18 以上用node -v检查。npm 或 npx 是否可用用npx --version检查。Python 版本如果 skill 是 Python 写的建议 3.10 以上。网络是否能访问 npm registry这个不用多说装包的时候自然会验证。如果npx playwright install失败最常见的原因是浏览器二进制文件下载超时。解决办法是设置镜像源或者手动下载。具体操作# 设置 npm 镜像源如果默认源慢 npm config set registry https://registry.npmmirror.com # 单独设置 Playwright 浏览器下载源 export PLAYWRIGHT_DOWNLOAD_HOSThttps://npmmirror.com/mirrors/playwright # 再执行安装 npx playwright install chromium这个问题的本质是 Playwright 默认从国外 CDN 拉浏览器包网络不稳定就会断。设置下载源之后成功率会高很多。这不是 skill 本身的问题而是依赖安装环节的通用问题。4.2 获取 skill 包的三种途径目前获取 skill 主要有三条路GitHub 直接 clone找到包含 skill 的仓库clone 下来把 skill 目录复制到本地 skills 路径。这是最通用的方式适合大多数情况。官方市场安装部分平台提供了npx skills install name之类的命令自动下载并放到正确位置。这种方式最省事但覆盖的 skill 数量有限。手动复制别人发给你的 skill 包解压后放到 skills 目录。这种方式适合内部共享。我一般推荐第一条路因为 GitHub 上的 skill 透明度高你能看到源码知道它到底干了什么。官方市场的 skill 虽然方便但有些是编译过的出了问题不好排查。实操心得clone 下来的 skill 不要直接放到全局 skills 目录先放到一个临时目录跑一遍确认没问题再移过去。我踩过一次坑一个 skill 的安装脚本会修改全局 npm 配置直接装到全局目录后把环境搞乱了。4.3 配置 skills 目录与加载顺序不同 Agent 对 skills 目录的要求不一样但通常支持两种位置全局目录比如~/.claude/skills/或者~/.codex/skills/所有项目都能用。项目目录比如项目根目录下的.skills/只对当前项目生效。加载顺序一般是项目目录优先于全局目录。如果两个目录里有同名 skill项目目录的会覆盖全局的。这个机制可以用来做“项目定制化”全局放通用 skill项目目录放针对这个项目的特殊 skill。配置的时候注意权限问题。skills 目录下的脚本需要有可执行权限否则 Agent 调用时会报 permission denied。用chmod x加上就行。# 查看 skills 目录结构 ls -la ~/.claude/skills/ # 给所有脚本加可执行权限 find ~/.claude/skills/ -name *.sh -exec chmod x {} \;4.4 跑通第一个 skill 的完整记录我拿一个最简单的 skill 来演示current-time功能是返回当前时间。这个 skill 只有一个 bash 脚本和一个元信息文件。元信息文件SKILL.md--- name: current-time description: 返回当前系统时间格式为 ISO 8601 when_to_use: 当用户询问当前时间、日期或者需要时间戳时使用 parameters: [] examples: - input: 现在几点了 output: 2025-01-15T10:30:0008:00 ---执行脚本run.sh#!/bin/bash date -Iseconds把这两个文件放到~/.claude/skills/current-time/目录下给run.sh加可执行权限然后重启 Agent。之后你问“现在几点了”Agent 就会调用这个 skill 并返回结果。这个过程看起来简单但包含了 skill 的完整生命周期定义元信息、编写执行逻辑、放置到正确目录、赋予权限、被 Agent 调用。把这五步跑通后面复杂的 skill 也是同样的套路。注意元信息文件里的when_to_use不要写得太宽泛。如果你写“当用户需要任何信息时使用”Agent 会在所有场景下都尝试调用这个 skill导致行为混乱。触发条件要具体到某个明确的意图。5. 常见问题与排查技巧实录5.1 skill 不被调用怎么办这是最高频的问题。你装了一个 skill问 Agent 相关问题它却不用。排查思路按以下顺序来检查元信息是否被加载有些 Agent 需要重启才能扫描到新 skill。先确认重启过了。检查 description 和 when_to_use 是否匹配把你问的问题和 skill 的触发条件对照一下看语义上是否对得上。检查 skill 数量是否过多超过 20 个之后匹配准确率下降试着临时移走一些不相关的 skill。检查是否有同名 skill 冲突两个 skill 名字太像Agent 可能选错。我遇到过一次skill 的when_to_use写的是“当用户需要截图时使用”但我问的是“帮我把这个页面存成图片”Agent 没匹配上。后来把when_to_use改成“当用户要求对网页进行截图、存为图片、保存页面快照时使用”命中率就上来了。触发条件里要包含用户可能用的同义词。5.2 依赖安装失败的典型场景热搜词里npx playwright install失败是一个典型。除此之外还有几种常见的依赖问题问题现象可能原因解决办法npm 包下载超时默认源网络不稳定切换镜像源浏览器二进制下载失败CDN 不可达设置 PLAYWRIGHT_DOWNLOAD_HOSTPython 包版本冲突全局环境已有旧版本用 venv 隔离脚本无执行权限文件权限不对chmod x路径包含空格脚本没加引号用 $VAR 包裹变量这些问题看起来琐碎但每一个都能让 skill 跑不起来。我的建议是在 skill 的元信息里写清楚依赖列表并在 README 里给出安装命令。这样别人拿到你的 skill 之后不用猜需要装什么。5.3 skill 执行超时或卡死有些 skill 会调用外部服务或者操作浏览器执行时间可能很长。如果 Agent 有超时限制skill 还没跑完就被中断了。解决办法有两个一是在 skill 内部设置合理的超时比如 curl 加--max-time 30二是把长任务拆成异步skill 先返回一个任务 IDAgent 过一会儿再查询结果。我一般建议单个 skill 的执行时间控制在 10 秒以内。超过 10 秒的任务要么优化逻辑要么改成异步。Agent 的交互体验很依赖响应速度一个 skill 卡 30 秒整个对话就断了。5.4 安全问题skill 能拿到什么权限skill 本质上是一段在你机器上执行的代码所以它能干的事情取决于你给它的权限。一个恶意的 skill 可以读取你的文件、发送网络请求、修改配置。防范措施只安装来源可信的 skill优先选 GitHub 上 star 多、有明确维护者的。安装前读一遍源码尤其是 shell 脚本和安装脚本看有没有可疑操作。用沙箱环境测试不确定的 skill 先在容器或者虚拟机里跑。限制 skill 的网络访问如果 skill 不需要联网可以在防火墙层面限制。注意不要因为某个 skill 功能诱人就跳过源码审查。我见过一个 skill 在安装脚本里偷偷往 crontab 里写定时任务虽然没造成实际损害但这种行为本身就很危险。5.5 常见问题速查表问题排查第一步常见根因skill 不触发重启 Agent元信息未加载触发但报错手动执行脚本依赖缺失或权限不足执行超时看脚本日志外部服务响应慢参数传错检查元信息参数定义类型不匹配多个 skill 冲突看调用日志描述重叠安装失败检查网络和镜像源CDN 不可达6. 进阶自己写一个 skill 并分发6.1 从需求到 skill 的转化方法写 skill 的第一步不是写代码而是把需求拆成“输入-处理-输出”三段。比如你想做一个“自动整理下载文件夹”的 skill输入下载文件夹路径、整理规则按类型/按日期处理扫描文件、分类、移动输出整理报告移动了哪些文件、去了哪里拆完之后再判断这个 skill 需不需要参数、需不需要外部依赖、执行时间大概多久。如果处理逻辑超过 100 行考虑拆成多个 skill 或者引入配置文件。我自己的习惯是先用伪代码把逻辑写一遍确认没有遗漏再翻译成实际代码。这样能避免写到一半发现逻辑不通推倒重来。6.2 元信息文件的编写规范元信息文件是 skill 的“说明书”写得好不好直接影响可用性。我的规范是name动词开头比如generate-qrcode、convert-markdown。description一句话包含动作和对象不超过 50 字。when_to_use列出 3 到 5 个触发场景用用户可能说的原话。parameters每个参数写明类型、是否必填、默认值、示例。examples至少两个例子一个简单一个复杂。--- name: convert-markdown description: 将 Markdown 文件转换为 HTML 文件 when_to_use: | 当用户要求将 Markdown 转为 HTML、 生成网页格式的文档、 或者需要 Markdown 的渲染结果时使用 parameters: - name: input type: string required: true description: Markdown 文件路径 - name: output type: string required: false default: ./output.html description: HTML 输出路径 examples: - input: 把 readme.md 转成 html output: 已生成 output.html ---这个格式不是强制的但字段越全Agent 理解得越准。6.3 分发 skill 的注意事项写完 skill 想分享给别人有几件事要做写 README说明 skill 的功能、依赖、安装步骤、使用示例。声明依赖在元信息或者单独的依赖文件里写清楚需要装什么。提供测试用例让别人能快速验证 skill 是否正常工作。标注版本用语义化版本号方便别人判断兼容性。选择分发渠道GitHub 仓库、官方市场、或者内部共享目录。我一般会在 GitHub 上建一个skills仓库每个 skill 一个子目录根目录放一个总的 README 说明每个 skill 的用途。这样别人 clone 下来就能用也方便我统一维护。实操心得分发之前在一个干净的机器上完整跑一遍安装和使用流程。你自己机器上能跑不代表别人机器上能跑。依赖缺失、路径写死、权限问题都是在干净环境里才会暴露出来的。7. 我对 skills 这套机制的实际体会用了几个月 skills 之后最大的感受是它把 AI Agent 的能力边界从“模型知道什么”扩展到了“模型能操作什么”。以前用 Agent 写代码它只能生成文本你得自己复制粘贴去执行。现在有了 skillAgent 可以直接调用工具、操作文件、访问网络真正变成一个能干活的东西。但 skills 也不是银弹。它的维护成本不低尤其是 skill 数量多了之后元信息的管理、依赖的更新、冲突的排查都需要花时间。我现在的做法是只保留高频使用的 skill低频的用完就删。与其维护一堆半死不活的 skill不如把常用的那几个打磨好。另外skill 的质量参差不齐。GitHub 上很多 skill 是别人随手写的没考虑边界情况参数校验也不做。用之前最好读一遍源码或者先在测试环境跑。我踩过最坑的一次一个 skill 在处理空输入时直接删除了目标目录幸好是在测试机上。最后分享一个小技巧给每个 skill 加一个--dry-run参数。执行的时候只打印会做什么不实际改动。这样在不确定 skill 行为的时候可以先 dry-run 一遍确认没问题再真正执行。这个习惯帮我避免了好几次误操作。