1. 从“skills”这个标题说起它到底指什么第一次看到“skills”这个标题很多人会以为是某个泛泛的能力清单或者一份简历上的技能罗列。但结合热搜词里的 Agent Skills、Google Cloud、npx、GKE、claude agent skills、codex skills 这些词基本可以确定这里说的 skills 不是人类的能力而是给 AI Agent 用的技能包——一套可安装、可调用、可复用的能力模块。打个比方大模型本身像一个刚毕业的高材生脑子好使但没上过班不知道你们公司的报销流程、代码规范、部署方式。Agent Skills 就是给这个高材生发的“员工手册 工具箱”让它知道遇到某类任务时该调用哪个流程、哪个脚本、哪个模板。它解决的核心问题是把一次性的提示词工程沉淀成可版本管理、可分发、可组合的标准化能力单元。这套东西适合谁三类人最该关注。第一类是天天写 prompt 的前端和全栈开发者你已经受够了每次都要复制粘贴一大段上下文第二类是搞 AI 应用落地的工程师需要把模型能力接进真实业务流程第三类是技术博主和工具党喜欢折腾新东西想第一时间搞清楚 Agent Skills 的安装、开发和分发逻辑。这篇文章我会从设计思路、核心机制、实操安装、开发流程到踩坑排查完整讲一遍尽量让你看完就能自己动手做一个 skill。需要先说明一点Agent Skills 目前还在快速演进不同平台Claude、Codex、Google Cloud 相关工具链的实现细节有差异。下面涉及具体命令和目录结构的部分我会以最常见的约定为主同时标注哪些地方需要你按自己所用平台的文档核对。这是基于常见实践的合理补全不是唯一标准答案。2. Agent Skills 的整体设计与思路拆解2.1 为什么需要 Skills 而不是继续堆 Prompt先说一个我自己的真实感受。早期做 AI 应用所有逻辑都塞在 system prompt 里一个 prompt 写到三千字改一个标点都要重新测一遍回归。后来发现这种做法的根本问题是耦合知识、流程、工具调用、输出格式全搅在一起没法单独维护。Agent Skills 的设计思路本质上是软件工程里的“关注点分离”搬到了 AI 能力层。一个 skill 通常包含几块东西一段描述这个技能干什么的元数据、一份指导模型如何思考和操作的指令、若干可选的脚本或资源文件。模型在运行时先看有哪些 skill 可用判断当前任务该不该触发某个 skill触发后再加载对应的详细指令。这样做的好处很直接。第一上下文按需加载。你不需要把所有能力都塞进每一次对话的上下文里只在需要时才把某个 skill 的完整内容拉进来省 token 也更聚焦。第二能力可组合。一个负责“读取数据库”的 skill 和一个负责“生成报表”的 skill 可以串起来用各自独立演进。第三可分发。skill 可以打包、可以放到市场、可以用 npx 一键安装这就从“个人技巧”变成了“团队资产”。2.2 一个 Skill 的典型结构长什么样虽然不同平台细节不同但一个 skill 的骨架高度相似。通常是一个目录里面有一个主描述文件常见命名是 SKILL.md 或类似的清单文件加上可选的脚本、模板、参考文档。主文件一般分两段前面是元信息比如名称、描述、触发条件后面是给模型看的操作指令。我拿一个“生成周报”的 skill 举例。元信息里写清楚这个 skill 叫 weekly-report当用户提到“周报”“本周总结”“汇报”这类词时考虑触发。指令部分则告诉模型先读取本周的 git commit 记录再按“完成事项 / 进行中 / 风险”三段式组织最后输出 Markdown。如果还需要调用脚本去拉 commit就放一个 scripts 目录里面塞一个取日志的脚本。这里有个关键设计点值得展开描述字段的写法直接决定 skill 会不会被正确触发。写得太窄模型永远想不起来用它写得太宽什么任务都往里套反而干扰判断。我的经验是描述里要同时包含“做什么”和“什么时候用”并且用具体的名词而不是抽象概念。比如写“处理数据”就不如写“把 CSV 文件转换成统计图表并输出 PNG”来得有效。2.3 和 MCP、插件、函数调用是什么关系热搜里出现了 claude mcpservers npx 这类词说明很多人会把 Agent Skills 和 MCPModel Context Protocol搞混。我用一句话区分MCP 解决的是“模型怎么连上外部工具和数据源”Skills 解决的是“模型知道该怎么做事”。MCP 更像一根标准化的数据线让模型能安全地访问文件系统、数据库、第三方 API。而 skill 是操作规程它可能用到 MCP 提供的连接能力也可能只是纯文本的指令。举个例子MCP 让模型能读到你本地的文件但“读完之后按什么格式整理成会议纪要”这件事是 skill 负责的。两者是互补关系不是替代关系。至于传统的函数调用function calling它更底层是模型输出一个结构化调用的机制。skill 可以封装一组函数调用把它变成一个有语义的完整能力。你可以理解为函数调用是螺丝刀MCP 是电源插座skill 是“如何组装这台机器”的说明书。3. 核心细节解析与实操要点3.1 安装方式npx 一键装与手动放置的区别热搜里 npx 出现频率很高还有“npx playwright install 失败”这种具体报错说明大家最关心的就是怎么把 skill 装起来。目前主流的安装方式有两种。第一种是命令行一键安装典型形式是npx some-skill-cli install skill-name。这种方式的好处是自动处理依赖、自动放到正确的目录、自动更新清单。坏处是它依赖网络和 npm 生态一旦网络抖动或者包本身有问题就会卡住。playwright install 失败就是典型例子它其实是在下载浏览器二进制跟 skill 本身关系不大但会让人误以为是 skill 装不上。第二种是手动放置。你从 GitHub 或者某个 skills 市场下载一个压缩包或目录解压后放到约定的 skills 目录里。这个目录的位置因平台而异常见的是项目根目录下的.skills/或者用户主目录下的配置文件夹。手动装的好处是完全可控坏处是容易放错位置、漏掉依赖。我个人的建议是先用一键安装跑通流程再研究它到底把文件放哪了。你可以在安装后去对应目录看一眼结构这样既省事又长知识。如果一键安装失败再退回手动方式反而更快。3.2 目录约定与命名规范不管你用哪个平台有几条命名和目录的约定是通用的踩过坑的人都知道这些细节有多重要。skill 名称用小写字母加连字符比如weekly-report、csv-to-chart不要用空格、下划线或大写很多加载器对大小写敏感。主描述文件的命名要严格按平台要求有的要求SKILL.md有的要求skill.yaml写错了直接不识别。脚本目录建议统一叫scripts模板叫templates参考文档叫references这样别人接手时一眼能看懂。如果 skill 需要读取外部文件路径尽量用相对路径并且明确说明相对于哪个基准目录。注意目录名里千万不要出现中文或特殊符号。我见过有人把 skill 目录命名成“周报生成”结果加载器直接报找不到排查了半小时才发现是编码问题。3.3 描述字段与触发条件的写法这是整个 skill 开发里最考验功力的一环。模型判断要不要用某个 skill主要靠描述字段的语义匹配。写得好模型该用的时候用、不该用的时候不碰写得差要么永远不触发要么到处乱触发。我的写法套路是“三段式”能力范围 触发场景 边界说明。举个例子name: csv-to-chart description: 把 CSV 数据文件转换成统计图表。当用户提供 CSV 文件路径并希望得到可视化图表、趋势图或对比图时使用。不适用于实时数据流或需要交互式图表的场景。这里“不适用于”那句就是边界说明能有效防止模型在错误场景下硬套。很多人写描述只写正面能力结果模型在完全不相关的任务上也尝试调用反而添乱。3.4 指令部分的组织给模型看的“操作手册”指令部分是 skill 的灵魂。它不是写给人类看的文档而是写给模型看的操作指南。所以写法上要步骤化、具体化、可执行。我一般按这个结构组织先说明这个 skill 的目标和最终产出是什么。列出执行步骤每一步说清楚输入、操作、输出。给出输出格式的模板或示例。列出常见错误和应对方式。关键技巧是多用祈使句少用描述句。写“读取文件”比写“模型应该读取文件”更有效。另外如果某一步需要调用脚本要明确写出脚本路径和参数格式比如运行 scripts/fetch_commits.sh参数为起始日期。4. 从零开发一个 Skill 的完整实操4.1 环境准备与依赖确认动手之前先把环境理清楚。你需要的东西不多但每一样都要确认版本。Node.js 环境因为很多安装工具是 npm 包建议用 LTS 版本。用node -v确认。一个可用的 AI Agent 运行环境比如支持 skills 的客户端或 CLI 工具。一个代码编辑器VS Code 就够。如果要写脚本确认对应的运行时比如 Python 或 Bash。我建议单独建一个工作目录来开发 skill不要直接在正式项目里改。因为开发过程中会反复安装、卸载、测试混在一起容易污染项目配置。建好目录后先跑一次npx 对应工具 --version确认工具链可用再开始。4.2 创建 Skill 骨架假设我们要做一个“把 git 提交记录整理成周报”的 skill名字叫git-weekly-report。第一步是建目录结构mkdir -p git-weekly-report/scripts cd git-weekly-report touch SKILL.md然后写 SKILL.md 的元信息部分。这里要注意不同平台对字段名要求不同常见的有name、description有的还要求version、author。我一般会先查一下所用平台的模板照着填避免字段名写错导致加载失败。元信息写完后开始写指令部分。我会先写一个最简版本只包含“读取 git log、按三段式整理、输出 Markdown”这三步先跑通再说。不要一上来就追求完美先让 skill 能被触发、能产出东西再迭代细节。4.3 编写核心脚本与参数处理如果 skill 需要执行实际操作比如拉取 git 日志就要写脚本。我用 Bash 写一个最简单的#!/bin/bash # scripts/fetch_commits.sh # 参数1起始日期格式 YYYY-MM-DD START_DATE$1 if [ -z $START_DATE ]; then echo 错误请提供起始日期 exit 1 fi git log --since$START_DATE --prettyformat:%h %s --no-merges这个脚本做了三件事接收日期参数、校验参数非空、输出格式化的提交记录。参数校验这一步很多人会省结果模型传了个空值进来脚本默默输出全部历史周报就变成了年度总结。所以脚本入口一定要做参数校验这是血泪教训。然后在 SKILL.md 的指令里明确写调用scripts/fetch_commits.sh传入本周起始日期。模型看到这条指令就会在合适的时候去执行。4.4 本地测试与触发验证写完骨架后最关键的一步是测试。测试分两层能不能被触发和触发后做得对不对。第一层测试我会在对话里输入几种不同的说法看模型是否在正确的时机调用这个 skill。比如输入“帮我整理一下这周的提交记录”应该触发输入“今天天气怎么样”不应该触发。如果该触发没触发多半是描述字段写得太窄如果乱触发多半是描述太宽或者边界没写清楚。第二层测试看输出质量。我会故意给一些边界情况比如本周没有任何提交、提交信息里有特殊字符、日期格式不对。观察 skill 是优雅处理还是直接崩掉。这一步能暴露大量问题比事后在真实场景里翻车强得多。提示测试时把每次的输入和输出记下来形成一个小的测试用例集。以后改 skill 时拿这套用例回归一遍能避免改好一个场景、弄坏另一个场景。4.5 打包与分发测试通过后如果想让别人也能用就要考虑打包。最简单的分发方式是把整个目录压缩别人解压放到 skills 目录即可。更规范的方式是发布到 npm 或者某个 skills 市场让别人用 npx 一键安装。发布到 npm 的话需要在 package.json 里配置好 bin 字段让安装命令能正确执行。这一步的坑在于包名要全局唯一而且要考虑别人安装时的目录权限问题。我建议先在本地用npm pack打包再用npm install 本地包路径模拟安装一遍确认没问题再发布。5. 常见问题与排查技巧实录5.1 安装类问题速查安装环节是报错重灾区我把常见问题和排查思路整理成表方便对照。现象可能原因排查方法npx 命令卡住不动网络问题或包体积大换网络环境或加--verbose看卡在哪一步提示找不到 skill目录位置不对或命名不符检查 skills 目录路径和目录名大小写安装成功但模型不调用描述字段没写触发条件检查 description 是否包含使用场景脚本执行报权限错误脚本没有可执行权限执行chmod x scripts/*.sh依赖下载失败缺少对应运行时确认 Python/Node 等运行时已安装playwright install 失败这类问题本质是二进制下载环节的问题跟 skill 逻辑无关。遇到这种先确认是不是网络或镜像源的问题不要急着怀疑 skill 本身。5.2 触发类问题该用的时候不用不该用的时候乱用这是最让人头疼的一类问题因为它没有明确报错只能靠观察。我的排查顺序是先看描述字段。把 description 单独拿出来读一遍问自己如果我是模型看到这段描述能判断出什么时候该用吗如果答案模糊那就是描述的问题。再看指令部分有没有冲突。有时候两个 skill 的描述高度重叠模型就会犹豫或者随机选一个。这时候要么合并要么把边界写得更清楚。最后看上下文长度。如果对话已经很长模型可能“忘记”了还有这个 skill 可用。这种情况可以考虑把 skill 的触发提示放在更靠前的位置或者精简其他上下文。5.3 输出质量不稳定的应对同一个 skill有时候输出很好有时候一塌糊涂这种波动很常见。原因通常有三个指令不够具体、缺少输出示例、模型本身的随机性。我的应对办法是加示例。在指令部分给出一个完整的输入输出示例模型照着模仿的准确率会明显提升。另外把输出格式用模板固定下来比如明确要求“必须包含三个二级标题分别是完成事项、进行中、风险”比笼统说“按三段式组织”要稳得多。如果还是不稳定可以考虑在脚本层面做更多处理把格式约束从“靠模型自觉”变成“靠代码保证”。比如让脚本直接输出结构化数据模型只负责润色这样波动就小很多。5.4 几个我踩过的坑第一个坑是路径写死。早期我在指令里写了绝对路径结果换台机器就找不到文件。后来全部改成相对路径并且明确说明基准目录才解决。第二个坑是忽略编码。脚本输出的中文在某些环境下会乱码导致模型读到的是乱码输出自然也是乱的。解决办法是在脚本里显式设置 UTF-8 编码。第三个坑是过度依赖模型判断。我一开始觉得模型很聪明什么都能自己判断结果发现它在边界情况上经常出错。后来我把能确定的逻辑都下沉到脚本里模型只做它擅长的语言组织和判断稳定性立刻上来了。6. Skills 的进阶玩法与生态观察6.1 组合多个 Skill 完成复杂任务单个 skill 能力有限真正的威力在于组合。比如一个“竞品分析”任务可以拆成三个 skill一个负责抓取公开信息一个负责结构化整理一个负责生成对比报告。模型按顺序调用每个 skill 各司其职。组合的关键是接口约定。前一个 skill 的输出格式要正好是后一个 skill 能接受的输入格式。这跟微服务之间的接口设计是一个道理。我一般会在 skill 的指令里明确写出“输出为 JSON字段包括 xxx”这样下游 skill 就能稳定解析。6.2 从 GitHub 和社区获取现成 Skill热搜里 github skills、skills 大全、skills 推荐这些词说明大家很想要现成的。目前社区里确实有不少开源 skill 集合覆盖代码审查、文档生成、数据分析等场景。获取渠道主要是 GitHub 仓库和各类 skills 市场。我的建议是先看再改不要直接用。别人的 skill 是针对他的场景写的直接拿来可能水土不服。正确做法是下载后读一遍指令和脚本理解它的设计意图再按自己的需求调整。这个过程本身也是学习 skill 开发的好机会。6.3 安全与权限的边界意识skill 能调用脚本、能读文件这就带来了权限问题。一个来路不明的 skill理论上可以执行任意脚本。所以只安装可信来源的 skill安装前看一眼脚本内容这是基本的安全习惯。另外涉及敏感数据的 skill要确认它的数据处理方式。比如它会不会把数据发到外部服务会不会在本地留下缓存。这些在正式使用前都要搞清楚。我个人的做法是涉及内部数据的 skill一律自己写或者经过代码审查后再用不直接装第三方的。6.4 这个方向接下来会怎么走从目前的趋势看Agent Skills 正在从“个人技巧”走向“标准化资产”。未来可能会出现更统一的描述规范、更完善的依赖管理、更细粒度的权限控制。对开发者来说现在投入时间学 skill 开发相当于早期学 Docker 或者早期学 npm回报是比较确定的。我自己的判断是skill 的编写能力会逐渐成为 AI 应用开发者的基本功就像今天写函数、写接口一样自然。早点上手早点积累自己的 skill 库这个复利效应会越来越明显。最后分享一个我自己的小习惯每当我发现自己在对话里重复写某段提示词超过三次我就会停下来把它抽成一个 skill。这个习惯帮我攒下了一套真正用得上的能力库而不是一堆装了没用的摆设。skill 这东西贵精不贵多能解决你实际问题的才是好 skill。