1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是某个泛泛的能力清单或者一份简历上的技能罗列。但结合热搜词里的 Agent Skills、Google Cloud、npx、AI agents 这些关键词基本可以锁定这里说的 skills是围绕 AI Agent 生态构建的一套“可插拔能力包”机制。简单讲就是给 AI 助手装上一个个独立的功能模块让它从“只会聊天”变成“能干活”。我最早接触这个概念是在折腾命令行 AI 工具的时候。当时想让 AI 帮我自动跑一遍前端项目的构建、截图、对比差异结果发现光靠提示词根本搞不定模型会“假装”执行实际什么都没发生。后来才明白Agent Skills 的核心价值就在于把“能力”从“语言描述”里剥离出来变成可安装、可调用、可复用的实体。你给它一个 skill它才真正拥有对应的执行权限和工具链。这套东西解决的核心问题是AI 的能力边界不再由模型参数决定而是由你安装了哪些 skills 决定。适合谁来参考三类人最该关注。第一类是前端、测试、运维这类需要重复执行固定流程的工程师skills 能把你的日常操作封装成 AI 可调用的动作第二类是研究 AI Agent 落地的开发者需要理解 skill 的加载、注册、调用链路第三类是想用 AI 写论文、做分镜、做自动化测试的内容创作者skills 能帮你把“想法”直接变成“产物”。热搜里还出现了“claude agent skills: a first principles deep dive”“codex skills”“github skills”这些词说明这套机制已经在多个 AI 工具生态里铺开。不同平台的 skill 格式、安装方式、调用协议不完全一样但底层逻辑是相通的一个 skill 就是一个带元数据的目录或包里面声明了它能做什么、需要什么参数、依赖什么环境AI 在运行时按需加载并执行。我写这篇东西的出发点很简单网上关于 skills 的资料要么太碎要么太偏某个平台缺少一份从“为什么这么设计”到“怎么装、怎么用、怎么排错”的完整梳理。下面我会按我实际踩坑的顺序把 Agent Skills 的选型逻辑、核心细节、实操流程和常见问题一次讲透。你不需要有很深的 AI 背景只要会敲命令行、看得懂目录结构就能跟着做。2. 内容整体设计与思路拆解2.1 为什么是“技能包”而不是“大提示词”很多人第一反应是我直接把操作步骤写进提示词不就行了我试过短期可以长期一定崩。原因有三个。第一提示词有长度限制复杂流程写到后面模型会“忘”前面的约束第二提示词无法真正执行系统命令模型只能“描述”它要做什么实际动作还得人来补第三提示词不可复用换个项目就得重写一遍维护成本极高。Agent Skills 的设计思路正好反过来把“能力”做成独立单元每个单元自带说明文档、执行脚本、依赖声明。AI 在需要的时候才去读这个单元的说明然后调用对应的脚本。这样做的好处是模型上下文里只保留“有哪些技能可用”的索引具体细节按需加载既省 token 又不容易出错。打个比方提示词像是你口头告诉助理“帮我订机票”而 skill 像是你给助理装了一个订票 App它自己知道怎么填信息、怎么支付、怎么出票。2.2 方案选型本地目录、包管理器还是云端市场热搜里出现了“claude 国内安装skills 官方市场”“skills下载平台有哪些”“skills安装包下载”这些词说明大家最关心的就是“从哪装”。我实际用下来skills 的来源大致分三类各有适用场景。第一类是本地目录直接挂载。你把 skill 文件夹放到指定路径AI 工具启动时扫描这个目录自动注册。这种方式最灵活适合自己开发、调试 skill改完立刻生效不用打包发布。缺点是换台机器就得重新拷一遍团队协作不方便。第二类是包管理器安装典型就是热搜里的 npx。npx 是 Node.js 生态的命令行工具很多 AI Agent 工具用它来拉取和运行 skill 包。比如npx playwright install就是安装浏览器自动化依赖的常见命令。用 npx 装 skill 的好处是版本可控、依赖自动解析适合用别人写好的成熟 skill。缺点是网络环境不好的时候容易卡住热搜里“npx playwright install失败”就是典型症状。第三类是云端市场或官方仓库比如 Google Cloud 生态里的 skill 注册中心、GitHub 上的 skill 合集。这种方式适合找现成的、经过社区验证的 skill但要注意甄别质量有些 skill 声明很美好实际跑起来一堆坑。我的建议是自己高频用的核心 skill 放本地目录团队共享的用包管理器锁版本尝鲜和找灵感去云端市场逛。三者不冲突可以混用。2.3 一个 skill 的最小结构长什么样不管哪个平台一个 skill 的骨架都差不多。我拿最常见的目录结构举例my-skill/ SKILL.md # 技能说明告诉 AI 这个技能能做什么、怎么调用 scripts/ run.sh # 实际执行脚本 package.json # 依赖声明如果是 Node 生态 assets/ # 可选模板、配置、静态资源SKILL.md是整个 skill 的灵魂。它通常包含三部分技能名称和一句话描述、输入参数说明、调用示例。AI 读的就是这个文件所以写得好不好直接决定 AI 会不会正确使用你的 skill。我见过太多人脚本写得没问题但SKILL.md写得含糊结果 AI 要么不调用要么传错参数。提示SKILL.md里的描述要用“动词对象结果”的句式比如“截取指定网页的完整截图并保存到指定路径”而不是“网页截图相关功能”。前者 AI 能直接匹配意图后者容易误判。2.4 加载机制AI 是怎么“发现”技能的理解加载机制排错的时候能省一半时间。大多数 Agent 工具的加载流程是这样的启动时扫描配置里声明的 skill 目录读取每个 skill 的元数据名称、描述、参数 schema把这些元数据塞进模型的系统提示里作为“可用技能列表”。当用户提出需求时模型判断哪个 skill 匹配然后按 schema 生成调用参数工具层执行对应脚本把结果返回给模型模型再组织成自然语言回复。这个链路里有两个关键点。第一元数据必须准确否则模型匹配不到第二脚本执行必须有明确的成功/失败返回否则模型不知道下一步该干嘛。我踩过的坑是脚本执行失败但没返回错误码模型以为成功了继续往下走最后输出一堆看似合理实则错误的结果。所以写 skill 脚本时一定要在失败时返回非零退出码并打印错误信息。3. 核心细节解析与实操要点3.1 SKILL.md 的写法决定 AI 会不会用你的技能SKILL.md不是随便写写就行的文档它是 AI 的“使用说明书”。我总结了一个可复用的模板实测下来 AI 调用准确率明显提升。--- name: web-screenshot description: 截取指定 URL 的完整网页截图并保存为 PNG 文件 parameters: - name: url type: string required: true description: 要截图的网页地址必须包含 http 或 https 前缀 - name: output type: string required: false description: 保存路径默认 ./screenshot.png - name: fullPage type: boolean required: false description: 是否截取完整页面默认 true --- # web-screenshot ## 用途 对指定网页进行截图支持整页和视口两种模式。 ## 调用示例 当用户说“帮我截一下 example.com 的图”调用本技能url 传 https://example.com。 ## 注意事项 - 目标页面必须是可公开访问的需要登录的页面会失败 - 截图超时时间为 30 秒超时会返回错误这个模板的关键在于参数用结构化 schema 声明而不是自然语言描述。结构化 schema 能让工具层做参数校验避免 AI 传错类型。我试过用纯自然语言写参数说明结果 AI 有时候把布尔值传成字符串 true脚本直接报错。3.2 脚本执行层退出码和输出格式的约定脚本是 skill 真正干活的部分。这里有几个硬性约定不遵守的话 AI 会“懵”。第一成功时退出码为 0失败时退出码非 0。这是最基本的。第二标准输出stdout放结果数据标准错误stderr放日志和错误信息。AI 通常只读 stdout你把错误信息混在 stdout 里AI 会当成正常结果处理。第三输出格式尽量用 JSON方便 AI 解析。如果输出是纯文本AI 也能读但结构化程度低容易误判。我写过一个批量重命名文件的 skill一开始脚本把“重命名成功”和“文件不存在”都打到 stdout结果 AI 把错误信息也当成成功结果汇报给用户。后来改成成功输出 JSON{renamed: 5}失败输出到 stderr 并返回退出码 1问题就解决了。3.3 依赖管理npx 和本地安装怎么选热搜里“npx playwright install失败”是个高频问题本质是依赖管理没做好。npx 的机制是如果本地没有这个包就去远程仓库拉取拉完执行。网络不通、镜像源配置不对、Node 版本不兼容都会导致失败。我的经验是开发阶段用 npx 快速验证生产环境或团队协作时改成package.json里声明依赖用npm install装到本地node_modules。这样版本锁定不依赖网络稳定性高很多。具体做法是在 skill 目录下建package.json{ name: my-skill, version: 1.0.0, dependencies: { playwright: ^1.40.0 } }然后脚本里用require(playwright)或import引用而不是每次 npx。这样第一次装好之后后续调用都是本地执行速度快且稳定。注意如果 skill 要分发给别人package.json里最好写清楚 Node 版本要求比如engines: {node: 18}。我遇到过 Node 16 跑不了某些新 API 的情况排查了半天才发现是版本问题。3.4 参数校验别让 AI 的“自由发挥”搞崩脚本AI 生成参数的时候偶尔会“自由发挥”。比如你声明 url 是必填它可能传个空字符串你声明 fullPage 是布尔值它可能传 yes。所以脚本入口处一定要做参数校验不能直接信任 AI 传来的值。我的做法是在脚本开头加一段校验逻辑const url process.argv[2]; if (!url || !/^https?:\/\//.test(url)) { console.error(Invalid url: must start with http:// or https://); process.exit(1); }这段代码看着简单但能挡掉大部分低级错误。校验失败时返回明确的错误信息AI 收到后有机会自我纠正重新生成参数。如果不校验脚本可能执行到一半才崩错误信息还不明确AI 就彻底卡住了。3.5 权限与安全边界skill 能碰什么不能碰什么skill 本质上是让 AI 执行系统命令所以安全边界必须划清楚。我给自己定的规矩是skill 脚本只操作项目目录内的文件不碰系统目录、不碰用户主目录下的敏感文件、不执行网络下载后直接运行的操作。具体做法上脚本里所有文件路径都基于一个明确的根目录变量比如process.env.SKILL_WORKDIR而不是直接用相对路径或绝对路径。这样即使 AI 传了个奇怪的路径也出不了工作目录。另外涉及删除、覆盖的操作脚本里要加确认逻辑或备份逻辑不能直接rm -rf。热搜里“自动挖洞skills”这类词让我有点警惕自动化安全测试类的 skill 尤其要注意边界别让 AI 在未授权的情况下扫描外部目标。我的原则是skill 的能力范围必须在SKILL.md里写清楚超出范围的请求直接拒绝执行。4. 实操过程与核心环节实现4.1 从零写一个可用的 skill完整流程我拿一个真实场景来演示写一个 skill让 AI 能自动对前端项目跑构建、启动本地服务、截图、然后关闭服务。这个流程在测试和验收环节特别常用。第一步建目录结构mkdir -p my-skills/frontend-screenshot/scripts cd my-skills/frontend-screenshot第二步写SKILL.md--- name: frontend-screenshot description: 对前端项目执行构建、启动本地服务、截图指定页面、关闭服务 parameters: - name: projectDir type: string required: true description: 前端项目根目录的绝对路径 - name: route type: string required: false description: 要截图的页面路由默认 / - name: output type: string required: false description: 截图保存路径默认 ./screenshot.png --- # frontend-screenshot ## 用途 自动化完成前端项目的构建、预览、截图流程适合验收和回归测试。 ## 调用示例 用户说“帮我截一下首页的图”调用本技能projectDir 传当前项目路径route 传 /。 ## 注意事项 - 项目必须已经安装依赖node_modules 存在 - 构建命令默认为 npm run build预览命令默认为 npm run preview - 截图超时 60 秒第三步写执行脚本scripts/run.sh#!/bin/bash set -e PROJECT_DIR$1 ROUTE${2:-/} OUTPUT${3:-./screenshot.png} if [ ! -d $PROJECT_DIR ]; then echo Project dir not found: $PROJECT_DIR 2 exit 1 fi cd $PROJECT_DIR echo Building... 2 npm run build 2 echo Starting preview server... 2 npm run preview SERVER_PID$! sleep 3 echo Taking screenshot... 2 npx playwright screenshot http://localhost:4173$ROUTE $OUTPUT kill $SERVER_PID echo {\output\: \$OUTPUT\, \route\: \$ROUTE\}第四步在 AI 工具的配置里声明 skill 目录重启工具让它扫描到新 skill。第五步测试。对 AI 说“帮我截一下首页的图”观察它是否调用了这个 skill参数是否正确截图是否生成。4.2 参数传递的坑路径、空格和引号上面脚本里PROJECT_DIR$1这种写法遇到路径带空格就会崩。比如/Users/me/my projectshell 会把空格当分隔符$1只拿到/Users/me/my。解决办法是调用时加引号脚本里也用引号包裹变量PROJECT_DIR$1 cd $PROJECT_DIR这个坑我踩过不止一次。AI 生成路径的时候不会主动加引号所以脚本内部必须自己处理。另外如果路径里有中文或特殊字符还要注意编码问题尽量用 UTF-8 环境。4.3 服务启动的等待策略sleep 不可靠上面脚本里用了sleep 3等预览服务启动这在实际操作中很不靠谱。机器快的时候 1 秒就好了机器慢的时候 5 秒还没起来截图就失败了。更稳的做法是轮询检测端口是否可访问for i in $(seq 1 30); do if curl -s http://localhost:4173 /dev/null; then break fi sleep 1 done这样最多等 30 秒一旦服务可用立刻继续既快又稳。这个技巧在写任何涉及“启动服务再操作”的 skill 时都适用。4.4 清理逻辑别让僵尸进程堆积脚本里npm run preview 启动的服务如果脚本异常退出进程可能残留下次再跑就端口冲突。所以要用trap确保退出时清理cleanup() { if [ -n $SERVER_PID ]; then kill $SERVER_PID 2/dev/null || true fi } trap cleanup EXIT这样无论脚本正常结束还是中途报错都会执行清理。我一开始没加这个跑了几次之后发现端口被占排查半天才发现是之前的进程没退干净。4.5 结果返回让 AI 知道“成了还是没成”脚本最后输出 JSON 到 stdout这是给 AI 看的。但要注意前面所有日志都重定向到了 stderr2只有最终结果走 stdout。这样 AI 读到的就是干净的 JSON不会把构建日志当成结果。如果截图失败脚本因为set -e会直接退出退出码非 0AI 收到失败信号可以决定是重试还是报告用户。这种“成功给数据、失败给信号”的模式是我试下来最稳的约定。5. 常见问题与排查技巧实录5.1 npx 安装失败从网络到缓存的完整排查热搜里“npx playwright install失败”是出现频率最高的问题之一。我整理了一个排查顺序按这个走基本能定位。排查项检查方法常见原因解决方式网络连通性curl -I https://registry.npmjs.org网络不通或代理配置错误检查网络设置确认能访问包仓库镜像源配置npm config get registry镜像源地址失效切换为可用的镜像源Node 版本node -v版本过低不支持新 API升级到 Node 18 或以上缓存损坏npm cache verify缓存文件损坏npm cache clean --force后重试权限问题看错误信息是否含 EACCES全局目录无写权限改用本地安装或修正目录权限磁盘空间df -h空间不足清理磁盘我遇到最多的是镜像源失效和缓存损坏。镜像源失效的表现是下载卡住或报 404缓存损坏的表现是报奇怪的校验错误。这两个用上面的方法都能解决。5.2 skill 不生效AI 根本没调用它有时候 skill 装好了但 AI 就是不调用。原因通常有三个。第一SKILL.md的 description 写得太模糊AI 匹配不到。解决办法是把 description 改成具体的“动词对象结果”句式。第二skill 目录没被扫描到检查配置文件里的路径是否正确重启工具后看日志有没有“loaded skill: xxx”。第三参数 schema 有语法错误导致整个 skill 加载失败这种情况日志里通常有报错。我建议每次新增 skill 后先手动问 AI“你现在有哪些可用技能”看它列出来的清单里有没有你的 skill。没有的话就是加载问题有的话就是匹配问题分开排查效率高很多。5.3 脚本执行超时怎么设置合理的超时时间AI 工具调用 skill 通常有超时限制默认可能是 30 秒或 60 秒。如果你的 skill 要跑构建、装依赖很容易超时。解决办法有两个一是把耗时操作拆成多个 skill分步调用二是在工具配置里调大超时时间。我一般把 skill 的执行时间控制在 30 秒以内。超过 30 秒的操作要么拆步骤要么改成异步skill 只负责启动任务并返回任务 IDAI 后续用另一个 skill 查询状态。这样每次调用都很快不会卡住。5.4 输出乱码编码问题的处理脚本输出中文时偶尔会乱码尤其是跨平台的时候。根源是编码不一致。解决办法是在脚本开头设置export LANGen_US.UTF-8或export LC_ALLen_US.UTF-8确保输出用 UTF-8 编码。如果 AI 工具读取时还是乱码检查工具的编码配置通常也有对应的设置项。5.5 独家避坑清单下面这些是我踩过坑之后总结的常规文档里不会写skill 名称不要用中文或空格用短横线连接的英文比如web-screenshot兼容性最好。SKILL.md里的示例要真实可执行AI 会模仿示例的格式生成参数示例错了它就跟着错。脚本里所有外部命令都要检查是否存在比如command -v npx /dev/null || exit 1避免命令找不到时报错不明确。涉及文件写入的 skill输出路径要支持相对路径和绝对路径AI 两种都可能传。测试 skill 时先用简单输入确认链路通了再上复杂场景别一上来就全流程跑出错了不好定位。多个 skill 之间有依赖关系时在SKILL.md里写明前置条件比如“需要先执行 build skill”AI 会按顺序调用。6. 技能生态的扩展玩法与个人体会6.1 把 skill 组合成工作流单个 skill 能力有限但组合起来就很强。比如我有三个 skillbuild、screenshot、diff。单独用只是三个功能但让 AI 按顺序调用就变成了“构建、截图、对比差异”的完整回归测试流程。AI 会根据SKILL.md里的描述自动编排顺序我只需要说“跑一遍回归测试”。这种组合玩法的关键是每个 skill 的输入输出要能衔接。比如build输出构建产物路径screenshot接收这个路径作为输入。我在SKILL.md里把参数描述写清楚AI 就能自动把上一个 skill 的输出传给下一个。6.2 从“用别人的”到“写自己的”热搜里“skills开发”“codex好用的skills”“skills推荐”这些词说明很多人已经过了“找现成”的阶段开始自己写。我的建议是从最小可用的 skill 开始别一上来就搞复杂流程。先写一个“读取文件并统计行数”的 skill跑通了再逐步加功能。每加一个功能就测试一次确保没破坏原有逻辑。写 skill 的过程其实也是梳理自己工作流的过程。很多平时靠肌肉记忆完成的操作写成 skill 的时候才发现步骤之间有隐含依赖这些依赖不写清楚AI 就会漏步骤。所以写 skill 反过来能帮你优化自己的工作流程。6.3 版本管理与团队共享skill 写多了之后版本管理就重要了。我的做法是每个 skill 独立一个 Git 仓库用 tag 标记版本。团队共享时在package.json里锁定版本号避免别人拉到不兼容的新版本。如果 skill 有 breaking change升大版本号并在SKILL.md里写清楚迁移说明。另外团队共享的 skill 最好加一个CHANGELOG.md记录每个版本改了什么。我遇到过同事更新了 skill 但没通知我这边调用参数对不上排查半天才发现是版本问题。有了 changelog看一眼就知道是不是版本导致的。6.4 我个人的使用体会用了一段时间 Agent Skills 之后最大的感受是AI 的能力上限不再取决于模型本身而取决于你给它装了什么。同一个模型装上不同的 skill能干的活完全不一样。这有点像给电脑装软件硬件是基础软件决定用途。另一个体会是skill 的质量比数量重要得多。我一开始装了一堆 skill结果 AI 经常选错或者选了但参数传不对。后来精简到常用的几个每个都仔细打磨SKILL.md和脚本整体成功率反而高了很多。所以别贪多先把核心场景的 skill 做扎实。最后分享一个小技巧每次 skill 执行失败后把错误信息和当时的输入记下来攒一段时间后回头看会发现失败模式就那么几种。针对这几种模式在脚本里加校验和提示skill 的稳定性会有质的提升。我现在维护的十几个 skill基本都是这么迭代出来的现在跑起来已经很稳了。