1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是某个泛泛而谈的能力清单或者一份简历上的技能罗列。但结合热搜词里的 Agent Skills、Google Cloud、npx、AI agents、claude agent skills、codex skills 这些词来看这里的 skills 显然不是指人类的能力而是指AI Agent 生态里可插拔、可复用、可分发的能力模块。简单说它就是给 AI 智能体装上的“技能包”——一个技能包对应一类具体任务比如操作浏览器、读写文件、调用某个云服务、生成分镜脚本、做论文检索等等。我最早接触这个概念是在折腾 AI 编程助手的时候。当时我让助手帮我跑一个前端项目的端到端测试它反复在“安装依赖”和“找不到浏览器”之间打转折腾了半小时也没跑通。后来我才意识到问题不在于模型不够聪明而在于它缺少一个封装好的、知道“先装什么、再配什么、最后怎么调用”的技能模块。把这件事拆成一个 skill 之后同样的任务从半小时缩短到两分钟。这就是 skills 存在的意义把零散的、需要多步操作的知识固化成一个 AI 可以直接调用的能力单元。所以这篇内容适合谁看如果你正在用 Claude、Codex 这类 AI 编程助手或者你在做 AI Agent 相关的开发又或者你只是好奇“为什么别人的 AI 好像什么都会我的 AI 却总是卡壳”那这篇就是写给你的。我会从设计思路、核心细节、实操过程到踩坑排查把 skills 这套东西讲透让你看完能自己动手做一个、装一个、改一个。2. 整体设计思路为什么 skills 是这么设计的2.1 核心问题AI 会思考但不会“记住流程”大模型的能力边界其实很清晰它擅长理解意图、生成内容、做推理判断但它不擅长记住“某个具体环境下的操作流程”。举个例子你让 AI 帮你部署一个静态站点它知道概念上要 build、要上传、要配 CDN但它不知道你的项目用的是哪个构建工具、产物目录叫什么、上传凭证放在哪。每次对话它都要重新问一遍或者猜错一遍。skills 的设计初衷就是解决这个“流程记忆”问题。它把一段可复用的操作流程连同触发条件、依赖声明、执行步骤、错误处理打包成一个结构化模块。AI 在遇到匹配的任务时自动加载对应 skill按既定流程执行。这就像给一个新员工配了一本操作手册他不用每次都想“这个按钮该不该点”照着手册做就行。2.2 方案选型为什么是“技能包”而不是“微调模型”有人会问既然想让 AI 学会特定任务为什么不直接微调模型我试过微调结论是微调适合改变模型的“表达风格”和“知识倾向”但不适合固化“操作流程”。原因有三点。第一微调成本高。每次流程变了你都要重新准备数据、重新训练、重新部署周期以天计。而 skill 改一个配置文件几分钟就能生效。第二微调不可组合。你微调了一个“部署技能”的模型又想让它同时会“测试技能”就得把两套数据混在一起训练容易互相干扰。而 skills 是模块化的装十个就是十个互不影响。第三微调不透明。模型内部到底学了什么你很难审计。而 skill 是明文的结构化描述每一步做什么、依赖什么、失败怎么办都写得清清楚楚出问题好排查。所以当前主流方案都选择了“技能包”路线用声明式的方式描述能力用运行时加载的方式注入 AI。Google Cloud 上的 Agent Skills、Claude 的 agent skills、Codex 的 skills本质上都是这个思路的不同实现。2.3 一个 skill 的典型结构长什么样虽然不同平台的 skill 格式略有差异但核心字段大同小异。我按最常见的结构给你拆一下name技能名称唯一标识通常用短横线命名比如playwright-e2e。description一句话说明这个技能干什么、什么时候触发。这段描述很关键AI 靠它判断该不该加载这个 skill。trigger / when触发条件可以是关键词、任务类型、文件模式等。dependencies依赖声明比如需要哪些命令行工具、哪些环境变量、哪些包。steps执行步骤按顺序列出每一步做什么、用什么命令、预期结果是什么。fallback失败处理某一步失败了该重试、跳过还是报错退出。examples示例输入输出帮助 AI 理解边界情况。这个结构看起来简单但每个字段的设计都有讲究。比如 description 为什么重要因为 AI 在决定用哪个 skill 时主要看的就是这段描述。如果描述写得太泛比如“处理文件”那它可能在不该触发的时候触发如果写得太窄又可能该用的时候用不上。我一般建议 description 里同时包含“动作”和“对象”比如“用 Playwright 对前端项目执行端到端测试并生成报告”这样匹配精度会高很多。3. 核心细节解析skill 开发中最容易踩坑的几个点3.1 触发条件写不好skill 要么乱触发要么不触发这是新手最容易翻车的地方。我见过一个 skilldescription 写的是“帮助处理数据”结果用户只要提到“数据”两个字它就加载哪怕用户只是在聊天里说“今天的数据不错”。另一个极端是 description 写得太具体比如“用 pandas 读取 CSV 文件并计算第三列均值”结果用户想算第四列均值时它反而不触发了。我的经验是触发描述要覆盖“意图”而不是“具体参数”。上面那个例子好的写法是“读取表格文件并做列级统计计算”这样不管用户算哪一列、用 CSV 还是 Excel都能匹配上。同时可以在 trigger 字段里补充一些关键词比如csv、excel、统计、均值作为辅助判断。还有一个技巧给 skill 加一个“负向触发”说明。比如“当用户只是询问数据概念、不涉及实际文件操作时不要加载本技能”。这能有效减少误触发。3.2 依赖声明不完整运行时才报错依赖这块我踩过最深的坑是本地开发时一切正常换到另一台机器就挂了。原因是我的 skill 依赖了一个全局安装的命令行工具但我没在 dependencies 里声明因为“我本地本来就有”。结果别人用的时候AI 执行到那一步才发现命令不存在整个流程中断。所以依赖声明要遵循一个原则凡是 skill 执行过程中用到的外部东西全部显式声明。包括命令行工具及其最低版本比如node 18、npx 9。需要安装的包比如playwright、pandas。环境变量比如API_KEY、PROJECT_ID。系统级依赖比如某些 skill 需要特定浏览器或字体。声明之后skill 在加载时可以先做一次依赖检查缺什么提前提示而不是执行到一半才崩。这个检查逻辑我建议写成 skill 的第一步成本很低但收益很大。3.3 步骤描述要“可执行”不能是“意图描述”写步骤时很多人会写成“配置好环境”“运行测试”“检查结果”这种意图性描述。这对人类来说够用但对 AI 来说太模糊了——“配置好环境”到底改哪个文件“运行测试”用哪条命令正确的写法是每一步都给出具体命令或具体操作并说明预期输出。比如执行npx playwright install chromium预期输出包含Chromium downloaded。执行npx playwright test预期退出码为 0。读取test-results/report.json检查failures字段是否为 0。这样 AI 执行时不需要猜照着做就行。如果某一步有多种可能可以在步骤里写条件分支比如“如果 package.json 里有 test 脚本执行 npm test否则执行 npx playwright test”。3.4 错误处理不能只写“报错退出”一个健壮的 skill 必须考虑失败路径。我见过太多 skill 只写了成功流程一旦某步失败就整个卡住AI 也不知道该怎么办。好的做法是给每个关键步骤配一个 fallback如果是网络超时重试 2 次间隔 5 秒。如果是依赖缺失提示用户安装并给出安装命令。如果是权限问题提示检查凭证配置。如果是数据格式不符尝试用备用解析方式。这些 fallback 不需要很复杂但要有。我一般会在 skill 末尾加一个“常见失败及处理”小节把已知的失败模式和对应处理列出来AI 遇到时可以直接查表。4. 实操过程从零做一个可用的 skill4.1 环境准备与工具选型假设我们要做一个“前端项目端到端测试”的 skill用 Playwright 作为测试工具。先确认环境Node.js 18 以上用node -v检查。npm 或 npx 可用用npx -v检查。一个待测试的前端项目假设它已经有package.json。这里为什么选 Playwright 而不是别的因为它在热搜词里出现了npx playwright install失败说明这是很多人实际在用的工具而且它跨浏览器、API 稳定、社区资料多。选工具时我一般看三点是否主流、文档是否完整、失败时是否好排查。Playwright 三项都满足。4.2 编写 skill 描述文件新建一个目录比如skills/playwright-e2e/在里面创建skill.md不同平台文件名可能不同有的叫SKILL.md有的叫skill.yaml按平台要求来。内容大致如下name: playwright-e2e description: 对前端项目执行 Playwright 端到端测试生成测试报告并汇总失败用例 trigger: keywords: [e2e, 端到端, playwright, 测试] filePatterns: [package.json, playwright.config.*] dependencies: - node 18 - npx 9 - playwright (通过 npx 自动获取) steps: - 检查 package.json 是否存在不存在则报错退出 - 执行 npx playwright install chromium安装浏览器 - 执行 npx playwright test运行测试 - 读取 test-results 目录下的报告文件 - 汇总通过数、失败数、失败用例名称 fallback: - 若 install 失败重试一次仍失败则提示检查网络 - 若 test 退出码非 0仍继续读取报告汇总失败信息 - 若报告文件不存在提示测试可能未生成报告这个文件写完后放到平台的 skills 目录下或者通过平台的安装命令加载。不同平台加载方式不同有的支持npx直接拉取有的需要手动放到指定目录具体看平台文档。4.3 参数计算与选择过程这里有一个容易被忽略的点超时时间设多少。Playwright 默认单用例超时 30 秒但实际项目中有些用例涉及登录、上传、等待接口可能超过 30 秒。我一般会先跑一次看最慢的用例耗时然后把这个值乘以 1.5 作为超时设置。比如最慢用例 45 秒那超时设 70 秒左右比较稳妥。另一个参数是并发数。Playwright 默认按 CPU 核心数并发但在 CI 环境里核心数可能很少导致跑得慢在本地开发机核心多又可能因为并发太高导致资源争抢。我的做法是本地开发用默认值CI 环境显式设workers2平衡速度和稳定性。这些参数不一定要写死在 skill 里可以写成“根据环境变量决定”比如PLAYWRIGHT_WORKERS有值就用它没值就用默认。这样 skill 更灵活。4.4 实操现场记录一次完整的 skill 执行我把上面这个 skill 装到我的 AI 助手里然后对它说“帮我跑一下这个前端项目的端到端测试。”以下是实际执行过程第一步AI 识别到关键词“端到端测试”匹配到playwright-e2eskill加载描述文件。第二步检查依赖。发现 node 版本 20npx 版本 10满足要求。检查 package.json 存在通过。第三步执行npx playwright install chromium。第一次执行时下载了约 150MB 的浏览器包耗时约 40 秒。这里有个细节如果之前装过这步会很快跳过。第四步执行npx playwright test。跑了 12 个用例其中 10 个通过2 个失败。退出码为 1。第五步读取报告。报告在test-results/report.json解析出失败用例名称和错误信息。第六步汇总输出“共 12 个用例10 通过2 失败。失败用例login.spec.ts 的‘错误密码应提示’、checkout.spec.ts 的‘库存不足应禁用按钮’。”整个过程约 2 分钟其中浏览器下载占了大头。第二次执行时因为浏览器已缓存总耗时约 35 秒。这个效率比我手动一步步敲命令快得多而且不会漏步骤。5. 常见问题与排查技巧实录5.1 npx playwright install 失败怎么办这是热搜词里出现的问题说明很多人遇到过。常见原因和排查顺序如下现象可能原因排查方法解决方式下载卡住不动网络到下载源不通看是否有进度输出换下载源或稍后重试提示权限不足目标目录不可写检查缓存目录权限改缓存目录或提权提示版本不兼容node 版本过低node -v检查升级 node 到 18安装后仍找不到浏览器缓存路径不一致检查PLAYWRIGHT_BROWSERS_PATH统一缓存路径我的经验是先看错误信息的第一行那里通常有最直接的原因。很多人被后面一堆堆栈吓到其实第一行就写清楚了。另外如果反复失败可以先把缓存目录清掉重来有时候是半下载状态导致的。5.2 skill 不触发或触发错误如果 skill 该触发时没触发先检查 description 和 trigger 是否覆盖了用户的实际表达。比如用户说“跑一下集成测试”而你的 trigger 只写了“端到端”那就匹配不上。解决办法是补充同义词或者把 trigger 写得更宽泛一些。如果 skill 不该触发时触发了比如用户只是问“端到端测试是什么”结果 skill 被加载了。这时候可以在 description 里加一句“仅当用户要求实际执行测试时触发概念咨询不触发”。AI 对这类负向描述的理解能力比想象中好。5.3 skill 执行到一半失败如何优雅退出失败不可怕可怕的是失败后状态混乱。比如测试跑了一半生成了部分报告AI 不知道该不该继续。我的做法是在 skill 里明确“失败后的状态处理”如果失败发生在依赖检查阶段直接退出不产生任何副作用。如果失败发生在执行阶段保留已生成的产物汇总已有信息然后退出。如果失败发生在汇总阶段输出原始报告路径让用户自己看。这样不管在哪一步失败用户都能拿到有用的信息而不是一个干巴巴的“出错了”。5.4 多个 skill 冲突怎么办当你装了很多 skill可能会出现两个 skill 都觉得自己该触发的情况。比如一个“测试 skill”和一个“部署 skill”都包含“构建”步骤。这时候 AI 可能会犹豫或者两个都加载导致重复执行。解决办法有两个一是给 skill 加优先级字段明确谁先谁后二是在 description 里写清楚边界比如“本技能只负责测试不负责构建和部署构建请用 build skill”。我一般两个都做双保险。6. skill 的扩展玩法与个人经验6.1 把 skill 组合成工作流单个 skill 解决单点问题多个 skill 串起来就能解决复杂问题。比如“测试 skill”“报告 skill”“通知 skill”就能实现“跑测试、生成报告、发通知”一条龙。组合的方式有两种一种是在一个 skill 里引用另一个 skill另一种是让 AI 根据任务自动编排。我试过第二种效果取决于 AI 的编排能力。任务简单时很顺任务复杂时偶尔会漏步骤。所以我现在更倾向于第一种把常用组合固化成一个“工作流 skill”里面按顺序调用各个子 skill。这样稳定性高很多。6.2 skill 的版本管理与分发skill 写多了之后版本管理就成了问题。我建议把 skill 目录纳入 git 管理每次修改都提交这样出问题可以回滚。分发方面如果团队内部用可以放在共享仓库里大家拉取即可如果要公开分享可以打包成压缩包或发布到平台的 skill 市场。这里有个细节skill 里不要硬编码个人路径、密钥、项目名。这些应该通过环境变量或参数传入。我见过一个 skill 里写死了/Users/zhangsan/project结果别人用的时候全报错。这种坑一次就够记一辈子。6.3 我个人的几条经验第一先写 description再写步骤。因为 description 决定了 skill 会不会被触发如果触发都不对步骤写得再好也没用。第二步骤要短但不要合并。每一步只做一件事这样失败时容易定位。我见过把五件事写在一个步骤里的 skill失败后根本不知道是哪件事出的问题。第三多写示例。示例比描述更能帮助 AI 理解边界。一个 skill 配三五个示例触发准确率和执行成功率都会明显提升。第四定期清理。装了不用的 skill 就删掉不然会干扰 AI 的判断。我一般每个月过一遍把三个月没用的 skill 归档。第五别怕改。skill 不是一次写完就固定的用着用着发现触发不准、步骤有漏就改。改一次比忍十次强。这套东西我用了大半年最大的感受是AI 的能力上限其实很高但它的“下限”取决于你给它的流程有多清晰。skills 就是用来抬高下限的。你把流程写清楚了AI 就能稳定发挥你写得含糊它就随机发挥。所以与其抱怨 AI 不好用不如花点时间把 skill 写好。这个投入产出比在我试过的所有 AI 优化手段里是最高的之一。